Documentation Tools

Changeset 261


Ignore:
Timestamp:
12/09/07 22:31:07 (4 years ago)
Author:
kate
Message:

The implementation is written up, and the document spellchecked and finished off. This proposal is now complete, unless I have accidentally missed something.

Location:
trunk/doc/namespaces
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/namespaces/appendix.xml

    r247 r261  
    1313                an idea of how using the system would feel.</para> 
    1414 
    15         <para>Additional modules correspond to the various other origional 
     15        <para>Additional modules correspond to the various other original 
    1616                intended formats for Doctools to render. Most notably this 
    1717                includes a module for <literal>puredocs</literal> (or several, 
    … …  
    6363 
    6464                                <para>Document descriptions and other metadata 
    65                                         are to be provided for the benifit of search systems, 
     65                                        are to be provided for the benefit of search systems, 
    6666                                        which especially suits &xhtml;.</para> 
    6767                        </listitem> 
    … …  
    9292 
    9393                        <listitem> 
    94                                 <para><literal>frontmatter</literal>: a titlepage, an abstract, 
     94                                <para><literal>frontmatter</literal>: a title page, an abstract, 
    9595                                        and other similar prefacing information.</para> 
    9696                        </listitem> 
    … …  
    9898                        <listitem> 
    9999                                <para><literal>structural</literal> elements: chapters, 
    100                                         sections, parts, appendicies, volumes, and so on. Tables 
     100                                        sections, parts, appendices, volumes, and so on. Tables 
    101101                                        of contents, figures and other listable items. Listable 
    102102                                        items are expected to be registered per-module, most 

  • trunk/doc/namespaces/entities.dtd

    r244 r261  
    55<!ENTITY bsc "<acronym>BSc</acronym>"> 
    66<!ENTITY css "<acronym>CSS</acronym>"> 
     7<!ENTITY cli "<acronym>CLI</acronym>"> 
    78<!ENTITY dtd "<acronym>DTD</acronym>"> 
    89<!ENTITY html "<acronym>HTML</acronym>"> 

  • trunk/doc/namespaces/implementation.xml

    r242 r261  
    66        <title>Implementation</title> 
    77 
     8        <para>The implementation outlined here describes the approach used for 
     9                proof-of-concept of the design proposed. It does not constitute a 
     10                full implementation specification (nor is one likely to be produced); 
     11                rather it serves as a guide for a small number of specific issues of 
     12                interest.</para> 
     13 
     14        <para>Various concepts from the previous Doctools design are expected to 
     15                remain applicable (most notably the theme system), although possibly 
     16                ported to a more appropriate language.</para> 
     17 
    818        <section> 
    9                 <title>Implementation</title> 
     19                <title>Hierarchy and code reuse</title> 
    1020 
    11                 <!-- TODO --> 
    12                 <para>* the lists of proposed modules may seem overwhelming. in practise, they are simply interfaces to much shared code</para> 
     21                <para>The directory hierarchy for module implementations is proposed as 
     22                        follows:</para> 
     23 
     24                <programlisting>module/moduleversion/outputformat/formatversion</programlisting> 
     25 
     26                <para>This hierarchy versions output formats for each module 
     27                        implementation. For the lists of proposed modules, this may seem 
     28                        overwhelming by the volume of versions involved. In practise, they 
     29                        are simply interfaces to shared code common to several 
     30                        versions.</para> 
     31 
     32                <para>For shared code, it is important to take care for inheritance 
     33                        between versions. There are two situations under which inheritance 
     34                        may occur; importing code from the same format of an earlier version 
     35                        (and then extending, or overriding that implementation), and 
     36                        importing code from an alternate format. Importing code from 
     37                        alternate formats forms <quote>cross-links</quote> in the tree: 
     38                        the ordering of these links is still subject to the versioning 
     39                        described previously. This would usually occur when versions of 
     40                        one format track the versions of another (as in the relationship 
     41                        between Docbook-simple and Docbook).</para> 
     42 
     43                <para>For example, <code>docbook-simple/v1.1/xhtml-strict/1.0</code> 
     44                        would contain the implementation for generating &xhtml; 1.0 from 
     45                        Docbook-simple v1.1. Since Docbook-simple tracks Docbook, this 
     46                        might import a cross-link from Docbook v4.3 (the Docbook version 
     47                        associated with Docbook-simple v1.1). For future versions of 
     48                        Docbook-simple (say v1.2), they may import their implementations 
     49                        from Docbook-simple v1.1. Likewise for future versions of &xhtml; 
     50                        the output versions (say 1.1) may import from &xhtml; 1.0.</para> 
     51 
     52                <para>Inevitably there will be portions of formats which will never be 
     53                        implemented. These do not make a module incomplete; the usual 
     54                        reason for these would be that the feature is irrelevant to the 
     55                        given output format. For example, Docbook's <code>@role</code> 
     56                        feature would usually not be expressed in output media, but some 
     57                        diagnostic message would be helpful, if the document author intends 
     58                        for some effect to happen.</para> 
     59 
     60                <para>There should be no reason for a module to contain a partial 
     61                        implementation (that is, to be incomplete), as modules should be 
     62                        small enough to be completable.</para> 
     63        </section> 
     64 
     65        <section> 
     66                <title>Interface</title> 
     67 
     68                <para>Two interfaces are proposed: a command-line tool for orchestrating 
     69                        builds and querying for information, and a library interface for 
     70                        programmatic use. As a convenience, Makefiles may be provided to ease 
     71                        the inclusion of the system into existing projects.</para> 
     72 
     73                <para>The modules employed to process a document may be inferred 
     74                        automatically from the document itself, if the document provides 
     75                        that information. If not, the required modules must be passed 
     76                        explicitly. Since each module's input format has a particular 
     77                        version, this must also be passed or inferred. When versions are 
     78                        inferred, the highest version is taken (as ordered by the module 
     79                        repository).</para> 
     80 
     81                <para>Likewise for output formats, it is expected that the user would 
     82                        not usually be interested in what version is being generated. 
     83                        Unless they explicitly restrict output to a specific version, 
     84                        as for inputs, the system defaults to the highest available.</para> 
    1385        </section> 
    1486 
    … …  
    1688                <title>Roadmap</title> 
    1789 
    18                 <para>* i/o tools for docbook-simple</para> 
     90                <para>The following order of implementation is rough, and proposed so as 
     91                        to maximise getting each area in place as quickly as possible. 
     92                        Once this underlying structure is solid, details may be implemented 
     93                        at a later date on top of that, without fear of disturbing the 
     94                        design.</para> 
     95 
     96                <orderedlist> 
     97                        <listitem> 
     98                                <para>&xslt; for docbook-simple, and a few other obvious 
     99                                        modules, to give a little meat to play with.</para> 
     100                        </listitem> 
     101 
     102                        <listitem> 
     103                                <para>&cli; orchestration tools and Makefile interfaces.</para> 
     104                        </listitem> 
     105 
     106                        <listitem> 
     107                                <para>Porting of themes from monolithic Doctools.</para> 
     108                        </listitem> 
     109 
     110                        <listitem> 
     111                                <para>&pdf; output. This should shake out a lot of orchestration 
     112                                        details, particularly if it requires two-passes (to convert 
     113                                        to &texml; and then to &context;)</para> 
     114                        </listitem> 
     115 
     116                        <listitem> 
     117                                <para>Puredocs' formats; these provide a little extra to play 
     118                                        with.</para> 
     119                        </listitem> 
     120 
     121                        <listitem> 
     122                                <para>Lots of little modules (as discussed in the 
     123                                        appendix).</para> 
     124                        </listitem> 
     125 
     126                        <listitem> 
     127                                <para>Processing for docbook-to-little-modules. This forms an 
     128                                        experiment in multi-stage processing, using our set of 
     129                                        modules as an intermediate format.</para> 
     130                        </listitem> 
     131                </orderedlist> 
     132        </section> 
     133 
     134        <section id="notes"> 
     135                <title>Notes</title> 
     136 
     137                <para>Notes may be passed between modules, similar in concept to the 
     138                        notes passed between Apache's modules. In our case, these are used 
     139                        to provide information which another module may use as part of its 
     140                        responsibility for processing, without requiring that module to 
     141                        know how to acquire the information.</para> 
     142 
     143                <para>An example illustrates this well; the <quote>figures</quote> 
     144                        module is not responsible for generating tables of contents 
     145                        for listable items. Likewise the <quote>structural</quote> module 
     146                        would not know what a figure is, or where to look for one. 
     147                        It is desirable for the structural module to be able to list such 
     148                        things, along with sections and chapters and suchlike.</para> 
     149 
     150                <para>So, the figures module leaves a note for the structural module 
     151                        to pick up (Exactly what might be listed is presumably 
     152                        user-configurable via some module-specific configuration 
     153                        option):</para> 
     154 
     155                <programlisting>structural:listable = 'figure'</programlisting> 
     156 
     157                <para>Here <code>structural:listable</code> means a note called 
     158                        <quote>listable</quote> stored in the <code>structural</code> 
     159                        namespace, which the structural module can pick up. Likewise 
     160                        the <quote>tables</quote> module also sets structural:listable. 
     161                        The ToC-rendering portion of the structural module looks for 
     162                        all these <code>structural:listable</code> notes, and generates 
     163                        a table of contents for each. The name <quote>listable</quote> 
     164                        is up to the structural module; consider it an analogue of a 
     165                        namespaced environment variable.</para> 
     166 
     167                <para>The options system may be implemented using this same 
     168                        mechanism.</para> 
    19169        </section> 
    20170 

  • trunk/doc/namespaces/previous.xml

    r242 r261  
    131131                                        were complex and difficult to understand. There 
    132132                                        was no way to customise behaviour without 
    133                                         modifying the codebase itself (a symptom of 
     133                                        modifying the code base itself (a symptom of 
    134134                                        a single-user project), and the set of supported 
    135135                                        formats was hardcoded.</para> 
Note: See TracChangeset for help on using the changeset viewer.