Docs/preparing.xml

   1 <!-- $Id: preparing.xml,v 1.5 2007/05/11 08:16:44 thuffir Exp $ -->
   2
   3 <section id="preparing">
   4 <title id="preparing.title">Preparing your source code for ROBODoc</title>
   5
   6     <para> ROBODoc allows you to mix the program documentation with
   7     the source code.  It does require though that this documentation
   8     has a particular layout so ROBODoc can recognize it.  There are
   9     three key concepts: headers, items, and sections.  </para>
  10
  11 <section>
  12 <title>Headers</title>
  13
  14     <para>Headers are the building blocks of the documentation. Lets
  15     look at an example. The following header was taken from the
  16     documentation of the predecessor of ROBODoc, AutoDoc.</para>
  17
  18 <example id="robodocheader">
  19     <title>A ROBODoc header in C.</title>
  20 <programlisting>
  21  /****f* financial.library/StealMoney
  22   *  NAME
  23   *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  24   *  SYNOPSIS
  25   *    error = StealMoney( userName, amount, destAccount, falseTrail )
  26   *  FUNCTION
  27   *    Transfer money from the Federal Reserve Bank into the
  28   *    specified interest-earning checking account.  No records of
  29   *    the transaction will be retained.
  30   *  INPUTS
  31   *    userName    - name to make the transaction under.  Popular
  32   *                  favorites include "Ronald Reagan" and
  33   *                  "Mohamar Quadaffi".
  34   *    amount      - Number of dollars to transfer (in thousands).
  35   *    destAccount - A filled-in AccountSpec structure detailing the
  36   *                  destination account (see financial/accounts.h).
  37   *                  If NULL, a second Great Depression will be
  38   *                  triggered.
  39   *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  40   *                  destAccount, a falseTrail structure must be
  41   *                  provided.
  42   *  RESULT
  43   *    error - zero for success, else an error code is returned
  44   *           (see financial/errors.h).
  45   *  EXAMPLE
  46   *    Federal regulations prohibit a demonstration of this function.
  47   *  NOTES
  48   *    Do not run on Tuesdays!
  49   *  BUGS
  50   *    Before V88, this function would occasionally print the
  51   *    address and home phone number of the caller on local police
  52   *    976 terminals.  We are confident that this problem has been
  53   *    resolved.
  54   *  SEE ALSO
  55   *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  56   *    financial/misc.h
  57   ******
  58   * You can use this space for remarks that should not be included
  59   * in the documentation.
  60   */
  61 </programlisting>
  62 </example>
  63     <para>A header consists of three different elements: a
  64     begin marker, a number of items, and an end marker.  The begin marker
  65     in the example is:</para>
  66
  67 <programlisting>
  68   ****f* financial.library/StealMoney
  69 </programlisting>
  70
  71 <para>It marks the beginning of a header.  It also tells ROBODoc
  72 </para>
  73 <itemizedlist>
  74     <listitem><para>the name of the element that is being documented, StealMoney,</para></listitem>
  75     <listitem><para>the module it is part of, financial.library,</para></listitem>
  76     <listitem><para>the kind of element, <literal>f</literal>, which stands for function.</para></listitem>
  77 </itemizedlist>
  78
  79 <para>
  80     ROBODoc always expects that a <literal>/</literal> separates the module name and an element name.
  81     So <literal>ModFoo/funcBar</literal>
  82     is a valid name, but <literal>funcBar</literal> is not.
  83     See <xref linkend="sections" endterm="sections.title" /> for more
  84     information.
  85 </para>
  86
  87 <para>
  88     Names can also contain spaces but ROBODoc won't create links to names with
  89     embedded spaces.
  90 </para>
  91
  92 <para>
  93     You can also have multiple names for a header. This is useful if you
  94     document similar objects together in one header (for example assembly
  95     subroutines with multiple jump-in points). Multiple names are separated by
  96     commas and can span over more than one line.
  97 <programlisting>
  98   ****f* financial.library/StealMoney, Steal_Money
  99 </programlisting>
 100     In the above example all references found to <literal>StealMoney</literal>
 101     and <literal>Steal_Money</literal> in other headers will be automatically
 102     linked to this header.
 103     The separation character(s) can be specified by the
 104     <xref linkend="separate_characters_block" endterm="separate_characters_block.title" />.
 105     See <xref linkend="customizing" endterm="customizing.title" /> for more
 106     information.
 107 </para>
 108
 109 <para>
 110 The end marker:
 111 </para>
 112
 113 <programlisting>
 114   ******
 115 </programlisting>
 116
 117     <para>
 118     marks the end of a header.
 119     </para>
 120
 121     <para>Items begin with an item name and are followed by the
 122     item's body.  An example: </para>
 123
 124 <programlisting>
 125   *  FUNCTION
 126   *    Transfer money from the Federal Reserve Bank into the
 127   *    specified interest-earning checking account.  No records of
 128   *    the transaction will be retained.
 129 </programlisting>
 130
 131     <para>
 132     In this case the item's name is FUNCTION.
 133     </para>
 134
 135     <para>
 136     Each line of an item starts with a remark marker.  In this case
 137     <literal>*</literal>.
 138     </para>
 139
 140 <para>That what ROBODoc needs to recognize a header is therefore:</para>
 141
 142 <example>
 143     <title>The markers needed by ROBODoc to recognize a header.</title>
 144 <programlisting>
 145  /****f* financial.library/StealMoney
 146   *  NAME
 147   *
 148   *  SYNOPSIS
 149   *
 150   *  FUNCTION
 151   *
 152   *
 153   *
 154   *  INPUTS
 155   *
 156   *
 157   *
 158   *
 159   *
 160   *
 161   *
 162   *
 163   *
 164   *
 165   *
 166   *  RESULT
 167   *
 168   *
 169   *  EXAMPLE
 170   *
 171   *  NOTES
 172   *
 173   *  BUGS
 174   *
 175   *
 176   *
 177   *
 178   *  SEE ALSO
 179   *
 180   *
 181   ******
 182 </programlisting>
 183 </example>
 184
 185     <para>
 186     The above example is in C.  ROBODoc supports many more
 187     languages though.  See <xref linkend="defaultheaders" endterm="defaultheaders.title" />.
 188     </para>
 189
 190 </section>
 191
 192
 193 <section id="header_types">
 194 <title id="header_types.title">Header Types</title>
 195
 196     <para> ROBODoc defines a number of header types.  You don't need
 197     to use them but they can be useful for sorting information.  The
 198     header type tells ROBODoc what kind of object you are documenting.
 199     This information allows ROBODoc to create more useful index
 200     tables.</para>
 201
 202     <para>The type is identified by one or two characters.  ROBODoc
 203     expects to find them after the fourth <literal>*</literal> in the
 204     begin marker.  So <literal>#****f</literal> is a valid marker,
 205     but <literal>#**f**</literal> is not.</para>
 206
 207     <para>If a single character is given, the type is defined as
 208     listed in the following table</para>
 209
 210 <table frame="all"><title>Default header types</title>
 211     <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 212         <colspec colname='c1'/>
 213         <colspec colname='c2'/>
 214         <tbody>
 215             <row><entry>c</entry><entry>Header for a class </entry></row>
 216             <row><entry>d</entry><entry>Header for a constant (from define)</entry> </row>
 217             <row><entry>f</entry><entry>Header for a function</entry></row>
 218             <row><entry>h</entry>
 219             <entry id="header_type_h">Header for a module in a project</entry></row>
 220             <row><entry>m</entry><entry>Header for a method</entry> </row>
 221             <row><entry>s</entry><entry>Header for a structure</entry>  </row>
 222             <row><entry>t</entry><entry>Header for a types</entry> </row>
 223             <row><entry>u</entry><entry>Header for a unit test</entry> </row>
 224             <row><entry>v</entry><entry>Header for a variable</entry>  </row>
 225             <row><entry>*</entry><entry>Generic header for everything else</entry> </row>
 226         </tbody>
 227     </tgroup>
 228 </table>
 229
 230     <para>If two characters are given, the first character should be
 231     <literal>i</literal> and the second can be any of the other
 232     characters from the table above.  This creates an internal header
 233     of the type specified by the second character.  Internal headers
 234     are special.  They can be used to hide certain headers. They are
 235     only extracted if requested. You can use them to document internal
 236     functions, classes, etc. that you do not want clients to see,
 237     creating what might be a programmer's manual as opposed to a
 238     user's manual.</para>
 239
 240     <para>So <literal>/****if* Module/func1</literal> defines an
 241     internal function called <literal>func1</literal>.
 242     </para>
 243
 244     <para>Headers marked internal are by default not included in the
 245     generated documentation.  If you want to include them use the
 246     option <option>--internal</option>.   You can also generate the
 247     documentation from only the internal headers with the option
 248     <option>--internalonly</option>.
 249     </para>
 250
 251     <para>You can define your own header types using the ROBODoc
 252     configuration file, <filename>robodoc.rc</filename>.
 253     See <xref linkend="headertypes_block" endterm="headertypes_block.title" />.
 254     This way you can document anything you like, for instance makefile
 255     entries, system tests, or exceptions.
 256     </para>
 257
 258 </section>
 259
 260 <section> <title>Items</title>
 261
 262     <para> By default ROBODoc recognizes the following items: </para>
 263
 264     <variablelist>
 265         <varlistentry>
 266             <term>
 267                 NAME
 268             </term>
 269             <listitem>
 270                 <para>Item name plus a short description.
 271                 </para>
 272             </listitem>
 273         </varlistentry>
 274
 275         <varlistentry>
 276             <term>
 277                 COPYRIGHT
 278             </term>
 279             <listitem>
 280                 <para>Who own the copyright : "(c) &lt;year&gt;-&lt;year&gt; by
 281                     &lt;company/person&gt;"
 282                 </para>
 283             </listitem>
 284         </varlistentry>
 285
 286         <varlistentry>
 287             <term>
 288                 SYNOPSIS
 289             </term>
 290             <term>
 291                 USAGE
 292             </term>
 293             <listitem>
 294                 <para>
 295                     How to use it.
 296                 </para>
 297             </listitem>
 298         </varlistentry>
 299
 300         <varlistentry>
 301             <term>
 302                 FUNCTION
 303             </term>
 304             <term>
 305                 DESCRIPTION
 306             </term>
 307             <term>
 308                 PURPOSE
 309             </term>
 310             <listitem>
 311                 <para>
 312                     What does it do.
 313                 </para>
 314             </listitem>
 315         </varlistentry>
 316
 317         <varlistentry>
 318             <term>
 319                 AUTHOR
 320             </term>
 321             <listitem>
 322                 <para>
 323                     Who wrote it.
 324                 </para>
 325             </listitem>
 326         </varlistentry>
 327
 328         <varlistentry>
 329             <term>
 330                 CREATION DATE
 331             </term>
 332             <listitem>
 333                 <para>When did the work start.
 334                 </para>
 335             </listitem>
 336         </varlistentry>
 337
 338         <varlistentry>
 339             <term>
 340                 MODIFICATION HISTORY
 341             </term>
 342             <term>
 343                 HISTORY
 344             </term>
 345             <listitem>
 346                 <para>Who has done which changes and when.
 347                 </para>
 348             </listitem>
 349         </varlistentry>
 350
 351         <varlistentry>
 352             <term>
 353                 INPUTS
 354             </term>
 355             <term>
 356                 ARGUMENTS
 357             </term>
 358             <term>
 359                 OPTIONS
 360             </term>
 361             <term>
 362                 PARAMETERS
 363             </term>
 364             <term>
 365                 SWITCHES
 366             </term>
 367             <listitem>
 368                 <para>
 369                     What can we feed into it.
 370                 </para>
 371             </listitem>
 372         </varlistentry>
 373
 374         <varlistentry>
 375             <term>
 376                 OUTPUT
 377             </term>
 378             <term>
 379                 SIDE EFFECTS
 380             </term>
 381             <listitem>
 382                 <para>What output is made.
 383                 </para>
 384             </listitem>
 385         </varlistentry>
 386
 387         <varlistentry>
 388             <term>
 389                 RESULT
 390             </term>
 391             <term>
 392                 RETURN VALUE
 393             </term>
 394             <listitem>
 395                 <para>
 396                     What do we get returned.
 397                 </para>
 398             </listitem>
 399         </varlistentry>
 400
 401         <varlistentry>
 402             <term>
 403                 EXAMPLE
 404             </term>
 405             <listitem>
 406                 <para>
 407                     A clear example of the items use.
 408                 </para>
 409             </listitem>
 410         </varlistentry>
 411
 412         <varlistentry>
 413             <term>
 414                 NOTES
 415             </term>
 416             <listitem>
 417                 <para>
 418                     Any annotations
 419                 </para>
 420             </listitem>
 421         </varlistentry>
 422
 423         <varlistentry>
 424             <term>
 425                 DIAGNOSTICS
 426             </term>
 427             <listitem>
 428                 <para> Diagnostic output.
 429                 </para>
 430             </listitem>
 431         </varlistentry>
 432
 433         <varlistentry>
 434             <term>
 435                 WARNINGS
 436             </term>
 437             <term>
 438                 ERRORS
 439             </term>
 440             <listitem>
 441                 <para>Warning and error-messages.
 442                 </para>
 443             </listitem>
 444         </varlistentry>
 445
 446         <varlistentry>
 447             <term>
 448                 BUGS
 449             </term>
 450             <listitem>
 451                 <para>Known bugs.
 452                 </para>
 453             </listitem>
 454         </varlistentry>
 455
 456         <varlistentry>
 457             <term>
 458                 TODO
 459             </term>
 460             <term>
 461                 IDEAS
 462             </term>
 463             <listitem><para>What to implement next and ideas. </para></listitem>
 464         </varlistentry>
 465
 466         <varlistentry>
 467             <term>
 468                 PORTABILITY
 469             </term>
 470             <listitem><para>Where does it come from, where will it work. </para></listitem>
 471         </varlistentry>
 472
 473         <varlistentry>
 474             <term>
 475                 SEE ALSO
 476             </term>
 477             <listitem><para>References to other functions, man pages, other documentation. </para></listitem>
 478         </varlistentry>
 479
 480
 481         <varlistentry>
 482             <term>
 483                 METHODS
 484             </term>
 485             <term>
 486                 NEW METHODS
 487             </term>
 488             <listitem><para>OOP methods.</para></listitem>
 489
 490         </varlistentry>
 491
 492
 493         <varlistentry>
 494             <term>
 495                 ATTRIBUTES
 496             </term>
 497             <term>
 498                 NEW ATTRIBUTES
 499             </term>
 500             <listitem><para>OOP attributes.</para></listitem>
 501         </varlistentry>
 502
 503
 504         <varlistentry>
 505             <term>
 506                 TAGS
 507             </term>
 508             <listitem>
 509                 <para>Tag-item description.
 510             </para></listitem>
 511         </varlistentry>
 512
 513         <varlistentry>
 514             <term>
 515                 DERIVED FROM
 516             </term>
 517             <listitem><para>OOP super class. </para></listitem>
 518         </varlistentry>
 519
 520         <varlistentry>
 521             <term>
 522                 DERIVED BY
 523             </term>
 524             <listitem><para>OOP sub class. </para></listitem>
 525         </varlistentry>
 526
 527         <varlistentry>
 528             <term>
 529                 USES
 530             </term>
 531             <term>
 532                 CHILDREN
 533             </term>
 534             <listitem><para>What modules are used by this one. </para></listitem>
 535         </varlistentry>
 536
 537         <varlistentry>
 538             <term>
 539                 USED BY
 540             </term>
 541             <term>
 542                 PARENTS
 543             </term>
 544             <listitem><para>Which modules do use this one. </para></listitem>
 545         </varlistentry>
 546
 547         <varlistentry>
 548             <term>
 549                 COMMANDS
 550             </term>
 551             <listitem><para>Command description. </para></listitem>
 552         </varlistentry>
 553
 554         <varlistentry>
 555             <term>
 556                 SOURCE
 557             </term>
 558             <listitem><para>Source code inclusion. </para></listitem>
 559         </varlistentry>
 560
 561     </variablelist>
 562
 563     <para>You can define your own items using the ROBODoc
 564     configuration file, <filename>robodoc.rc</filename>.  See <xref
 565     linkend="customizing" endterm="customizing.title" />.  </para>
 566
 567 </section>
 568
 569 <section id="sections">
 570 <title id="sections.title">Sections</title>
 571
 572     <para>The structure of source code for a project is usually
 573     hierarchical.  A project might consists of several applications,
 574     an application of several modules, a module of several functions
 575     or even sub modules.  ROBODoc allows you to show this hierarchy in
 576     your documentation.  For this you specify the hierarchy in the
 577     header name.  For instance,  you have a project that is going to
 578     create a new language called D.  The D Language project might
 579     consists of three applications: a preprocessor, a compiler, and a
 580     linker.  The compiler consists of two modules, a parser and a
 581     generator.  The parser module consists of several
 582     functions.</para>
 583
 584     <para>The following three headers show how this hierarchy can be
 585     defined in the header name.</para>
 586
 587 <programlisting>
 588 #****h* D-Language/Compiler
 589 # FUNCTION
 590 #   The compiler takes a preprocessed source file and
 591 #   turns it into an object file.
 592 #***
 593 </programlisting>
 594
 595 <programlisting>
 596 #****h* D-Language/Linker
 597 # FUNCTION
 598 #   The linker module contains functions that scan a
 599 #   object file and build the executable.
 600 #***
 601 </programlisting>
 602
 603 <programlisting>
 604 #****h* Compiler/Parser
 605 # FUNCTION
 606 #   The parser module contains functions that scan a
 607 #   preprocessed source file and build the syntax tree.
 608 #***
 609 </programlisting>
 610
 611 <programlisting>
 612 #****f* Parser/ReadToken
 613 # FUNCTION
 614 #   ReadToken reads the next token from the input
 615 #   file.
 616 #***
 617 </programlisting>
 618
 619     <para>When you generate documentation with the option
 620     <option>--section</option>, ROBODoc uses the hierarchical
 621     information when generating the table of contents and document
 622     section information. For instance in HTML sections are started
 623     with &lt;H1&gt;,  &lt;H2&gt;,  &lt;H3&gt; depending on the level
 624     in the hierarchy.  The table of contents will also contain levels.  The
 625     table of contents for the above example will be: </para>
 626
 627 <programlisting>
 628 1. D-Language/Compiler
 629 1.1 Compiler/Parser
 630 1.1.1 Parser/ReadToken
 631 2. D-Language/Linker
 632 </programlisting>
 633
 634 </section>
 635
 636 <section id="formatting"> <title id="formatting.title">Smart Text Formatting</title>
 637
 638 <para>By default ROBODoc creates preformatted text in the output
 639 documentation for all the text it finds in an item.  This means
 640 that the formatting of the output looks the same as the formatting of
 641 the text of an item.  Line-breaks and indentation stay the same.
 642 This is easy but does not always create the best looking
 643 output.</para>
 644
 645 <para>ROBODoc can also try to deduce the formatting of your text based
 646 on the layout and indentation of your text and on special characters in the text.
 647 It works a bit similar to the input method of Wikis.  In the context of this
 648 manual this is called Smart Formatting.
 649 </para>
 650
 651 <para>You switch this on with the option <option>--nopre</option>.
 652 ROBODoc now tries to find three kind of elements: paragraphs,
 653 lists, and preformatted text.</para>
 654
 655 <para>Paragraphs are separated by empty lines.  So the following item
 656 has two paragraphs.</para>
 657
 658 <example>
 659     <title>Two paragraphs.</title>
 660 <programlisting>
 661   FUNCTION
 662     This function does something.
 663
 664     And it then does something else
 665     and a bit more.
 666 </programlisting>
 667 </example>
 668
 669 <para> A List starts with a line that ends with a ':' which is then
 670 followed by one or more list items. List items should start with '*',
 671 '-', or 'o'.   So the following item contains a valid list: </para>
 672
 673 <example>
 674     <title>A list.</title>
 675 <programlisting>
 676   FUNCTION
 677      This function does:
 678      * a lot of foo
 679      * some snafuing
 680      * and a bit of foobarring.
 681 </programlisting>
 682 </example>
 683
 684 <para> A list item can span more than one line if the second and following
 685 lines are indented.  So this is also a valid list:</para>
 686
 687 <example>
 688     <title>A list where one of the items spans more than one line.</title>
 689 <programlisting>
 690   FUNCTION
 691      This function does:
 692      * a lot of foo and preprocessing of the
 693        raw input with the aid
 694        of the some magic
 695      * some snafuing
 696      * and a bit of foobarring.
 697 </programlisting>
 698 </example>
 699
 700
 701 <para>If list items directly follow the name of a robodoc item they
 702 also form a valid list.  So this is a valid list:</para>
 703
 704 <example>
 705     <title>an implicit list</title>
 706 <programlisting>
 707   INPUTS
 708     * inputname -- the name of the input file
 709     * outputname -- the name of the output file
 710     * n -- the number of characters to be written
 711 </programlisting>
 712 </example>
 713
 714 <para> Preformatted text is indicated by indenting it more that the
 715 surrounding text.  The first non-empty line in an item determines the
 716 base indenting.  Any lines with an indentation larger than this are
 717 preformatted.  An example:</para>
 718
 719 <example>
 720     <title>Preformatted text</title>
 721 <literallayout class="monospaced">
 722    FUNCTION
 723      The following lines are preformatted
 724         +--------+
 725         | A box  |
 726         |        |
 727         +--------+
 728      End of the preformatted text.
 729 </literallayout>
 730 </example>
 731
 732 <para>The following is a complete example.</para>
 733
 734 <example id="fullsmart">
 735     <title>All three elements of smart formatting.</title>
 736 <literallayout class="monospaced">
 737     This is some example text.
 738     And some more.
 739
 740     This is even more, and we start a list:
 741     * a list item
 742     * a list item
 743     * a list item
 744
 745     And we can also do preformatted stuff
 746     by indenting
 747         +--------+
 748         |        |
 749         +--------+
 750     The box will stay.
 751 </literallayout>
 752 </example>
 753
 754 <para>will be turn into</para>
 755
 756 <example id="fulloutput">
 757     <title>The corresponding HTML output.</title>
 758 <literallayout class="monospaced">
 759     &lt;p&gt;This is some example text.
 760     And some more.&lt;/p&gt;
 761
 762     &lt;p&gt;This is even more, and we start a list:&lt;/p&gt;
 763     &lt;ul&gt;
 764     &lt;li&gt;a list item&lt;/li&gt;
 765     &lt;li&gt;a list item&lt;/li&gt;
 766     &lt;li&gt;a list item&lt;/li&gt;
 767     &lt;/ul&gt;
 768
 769     &lt;p&gt;And we can also do preformatted stuff
 770     by indenting&lt;/p&gt;
 771     &lt;pre&gt;
 772         +--------+
 773         |        |
 774         +--------+
 775     &lt;/pre&gt;
 776     &lt;p&gt; The box will stay.&lt;/p&gt;
 777 </literallayout>
 778 </example>
 779
 780 </section>
 781
 782 </section>
 783
 784