RoboDoc 4.0.18 说明书

Frans Slothouber and Petteri Kettunen

翻译：李若

简单介绍

当我们在进行软件开发的时候，常常需要同时维护程序代码和软件文档。由于程序代码和软件文档分别在不同的文件中，同时对它们进行维护是一个比较困难的工作。其困难之处在于两者比较脱节，保持同步事实上完全依赖于人工的控制，在比较大的开发工作中会出现问题，另一个是在程序代码中我们常常还需要加入详尽的注释，这对于开发者来说是一个工作量上的浪费，这些注释事实上和文档在很大程度上是完全相同的，我们需要在程序代码和文档中分别进行更新。那么，我们可不可以直接从程序代码中的注释产生软件的文档，就不需要另外维护一份文档了呢？这样，我们程序代码中的注释可以更加详尽，不单单是对程序的代码行进行简单的解释，并且能够写入描述整个算法和程序结构的内容，使得我们的程序具有更好的可读性，并且在程序进行维护的时候，由于程序代码和注释完全组合在一起，我们就可以方便的进行同步的更新。

这里有一个好消息：这样的愿望是现在可以实现的了！现在，已经有了一些专门帮助我们进行这样的工作开发工具了，比如 KDE 开发组开发的 kdoc、还有一个叫做 doxygen 的工具，都是这个方面的好帮手。据我所知，kdoc 和 doxygen 支持很多不同的程序设计语言，但是都不支持 Fortran。进一步的好消息是：RoboDoc 也是一个这样的工具，并且能够支持Fortran，在做科学与工程计算界中，很多开发者喜爱使用 Fortran 进行开发，现在在 Fortran 中我们也能够使用这样方便的开发方式了。

RoboDoc 的取得和安装

RoboDoc 是一个使用 GPL 的软件，它的主页在 http://robodoc.sourceforge.net ，您可以在它的主页上拿到它的最新版本的源代码。在您拿到源代码以后，其中有文档告诉您详细的安装步骤，安装的过程非常简单，这里就不仔细说了。

RoboDoc 的使用

和其他相似的软件一样，使用 RoboDoc 的方法主要是分为下面几个步骤：

在您的程序代码中按指定的格式写入文档和注释；
设定 RoboDoc 的配置文件；
使用 RoboDoc 处理您的程序代码，得到文档； RoboDoc 由于比较简单，您甚至可以直接在命令行直接指定其配置选项，就可以不用写配置文件了；

我们下面一步一步的来说明上面使用步骤。

程序代码中文档和注释的格式

在 RoboDoc 能够识别的注释中，下面这几个概念是关键的：头部、条目、段

头部头部是用来识别文档的结构的关键部分。这里有一个例子，是从 RoboDoc 的预处理器 AutoDoc 的文档中取出来的：

 /****f* financial.library/StealMoney
  *  NAME
  *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  *  SYNOPSIS
  *    error = StealMoney( userName, amount, destAccount, falseTrail )
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
  *  INPUTS
  *    userName    - name to make the transaction under.  Popular
  *                  favorites include "Ronald Reagan" and
  *                  "Mohamar Quadaffi".
  *    amount      - Number of dollars to transfer (in thousands).
  *    destAccount - A filled-in AccountSpec structure detailing the
  *                  destination account (see financial/accounts.h).
  *                  If NULL, a second Great Depression will be
  *                  triggered.
  *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  *                  destAccount, a falseTrail structure must be
  *                  provided.
  *  RESULT
  *    error - zero for success, else an error code is returned
  *           (see financial/errors.h).
  *  EXAMPLE
  *    Federal regulations prohibit a demonstration of this function.
  *  NOTES
  *    Do not run on Tuesdays!
  *  BUGS
  *    Before V88, this function would occasionally print the
  *    address and home phone number of the caller on local police
  *    976 terminals.  We are confident that this problem has been
  *    resolved.
  *  SEE ALSO
  *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  *    financial/misc.h
  ******
  * You can use this space for remarks that should not be included
  * in the documentation.
  */

一个头部包含有三个不同的部分：一个起始标志、一些条目和一个结束标志。上面这个例子中，起始标志为：

****f* financial.library/StealMoney

RoboDoc 读到这个标志，就知道一个文档的头部开始了，并且它指定了随后的这段文档的名字为 StealMoney ，这段文档是作为文档段 financial.library 的一部分的。这段文档的类型标识为 f ，表示这是一个函数的文档。RoboDoc 要求您必须提供用一个斜杠 / 分开的文档段名称对，用来将文档按树型结构组织起来。在段部分，我们还会仔细讨论。

结束标志为
******
用来表示一个头部的结束。

每个条目由一个条目名开头，后面的部分是该条目的内容，例如
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
  
这里条目名称为 FUNCTION，条目的每一行都是由一个注释标志开始，这个例子里是一个 * 号。

上面的这个例子是一个 C 程序的例子，RoboDoc 支持很多种的程序语言。下面列举的是所有的 RoboDoc 支持的注释标志：
/****       C, C++
 *
 ***/
//****      C++
//
//***
(****       Pascal, Modula-2
 *
 ***
 *)
{****       Pascal
 *
 ***
 *}
;****       M68K assembler
;
;***
****        M68K assembler, COBOL
*
***
C     ****  Fortran
C     
C     ***
REM ****    BASIC
REM *
REM ***
%****       LaTeX, TeX, Postscript
%
%***
#****       Tcl/Tk
#
#***
--****      Occam
--
--***
<!--****     HTML Code
*
***
<!---****    HTML Code
*
***
|****       GNU Assembler
|
|***
$!****      DCL
$!
$!***
'****       Visual Basic, Lotus script
'*
'***
.****       DB/C
.*
.***
!!****      FORTRAN 90
!!
!!***
!****       FORTRAN 90
!
!***
这些注释标志还可以混合使用，并不仅仅限于上面所列举的这些程序设计语言。所以如果您使用的程序设计语言使用的是 # 作为注释标志的话，您可以使用 Tcl/Tk 的注释标志，写下面形式的头部：
#****f* Foo/Bar
# FUNCTION
#   Bar snarfs the Foo input and mangles it.  Given the right settings
#   it might also do a bit of snu snu.
#***

头部的类型标识

RoboDoc 定义了一系列的头部类型标识，您不一定要使用它们，但是使用正确的头部类型标识可以使得文档被更好的分类组织起来。头部类型标识告诉了 RoboDoc 您是在为什么对象写文档，这样 RoboDoc 就能够产生更加有用的文档索引。

头部类型表示是使用一到两个字符标识的。RoboDoc 会将头部其实标志后的第四个 * 号后面读取它，所以

#****f

是一个正确的头部类型标识，而

#**f**

就不对。

使用单个字符标识的头部类型如下表

标识符标识符指定的类型

c Header for a class.

d Header for a constant (from define).

f Header for a function.

h Header for a module in a project.

m Header for a method.

s Header for a structure.

t Header for a types.

u Header for a unittest.

v Header for a variable.

* Generic header for every thing else.

标识符	标识符指定的类型
c	Header for a class.
d	Header for a constant (from define).
f	Header for a function.
h	Header for a module in a project.
m	Header for a method.
s	Header for a structure.
t	Header for a types.
u	Header for a unittest.
v	Header for a variable.
*	Generic header for every thing else.

如果使用两个字符来指定，那么第一个字符必须是 i ，第二个字符是上表中的任一字符。这将会产生一个内部的头部类型。内部的头部类型是比较特殊的，能够用来隐藏一些头部，只有当您指定将这些头部进行展开的时候，它们才会被展开。这样您就可以写一些给内部的开发者使用，而不想给用户看到的文档。比如 /****if* Module/func 就可以定义一个内部的叫做 func 的函数的文档。

被指定为内部头的文档缺省的将不会被产生出来。您可以通过使用选项

--internal

将它们产生出来，而且通过使用选项

--internalonly

您可以单独将内部文档产生出来。

通过修改全局配置文件 robodoc.rc，您还可以自己定义头部类型，这样您就可以自由的对任何东西进行操作了。

条目

在缺省情况下，RoboDoc 会识别下面的这些条目：

条目名条目的内容

NAME Item name plus a short description.

COPYRIGHT Who own the copyright : "(c) - by "

SYNOPSIS, USAGE How to use it.

FUNCTION, DESCRIPTION, PURPOSE What does it do.

AUTHOR Who wrote it.

CREATION DATE When did the work start.

MODIFICATION HISTORY, HISTORY Who has done which changes and when.

INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES What can we feed into it.

OUTPUT, SIDE EFFECTS What output is made.

RESULT, RETURN VALUE What do we get returned.

EXAMPLE A clear example of the items use.

NOTES Any annotations

DIAGNOSTICS Diagnostic output

WARNINGS, ERRORS Warning and error-messages.

BUGS Known bugs.

TODO, IDEAS What to implement next and ideas.

PORTABILITY Where does it come from, where will it work.

SEE ALSO References to other functions, man pages, other documentation.

METHODS, NEW METHODS OOP methods.

ATTRIBUTES, NEW ATTRIBUTES OOP attributes

TAGS Tag-item description.

COMMANDS Command description.

DERIVED FROM OOP super class.

DERIVED BY OOP sub class.

USES, CHILDREN What modules are used by this one.

USED BY, PARENTS Which modules do use this one.

SOURCE Source code inclusion.

同样的，通过修改 robodoc.rc ，您还可以自己增加条目。

条目名	条目的内容
NAME	Item name plus a short description.
COPYRIGHT	Who own the copyright : "(c) - by "
SYNOPSIS, USAGE	How to use it.
FUNCTION, DESCRIPTION, PURPOSE	What does it do.
AUTHOR	Who wrote it.
CREATION DATE	When did the work start.
MODIFICATION HISTORY, HISTORY	Who has done which changes and when.
INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES	What can we feed into it.
OUTPUT, SIDE EFFECTS	What output is made.
RESULT, RETURN VALUE	What do we get returned.
EXAMPLE	A clear example of the items use.
NOTES	Any annotations
DIAGNOSTICS	Diagnostic output
WARNINGS, ERRORS	Warning and error-messages.
BUGS	Known bugs.
TODO, IDEAS	What to implement next and ideas.
PORTABILITY	Where does it come from, where will it work.
SEE ALSO	References to other functions, man pages, other documentation.
METHODS, NEW METHODS	OOP methods.
ATTRIBUTES, NEW ATTRIBUTES	OOP attributes
TAGS	Tag-item description.
COMMANDS	Command description.
DERIVED FROM	OOP super class.
DERIVED BY	OOP sub class.
USES, CHILDREN	What modules are used by this one.
USED BY, PARENTS	Which modules do use this one.
SOURCE	Source code inclusion.

段

一个开发项目的源码常常是树型结构的，项目包含着几个应用，每个应用又有几个模块，每个模块都有一些函数或者几个子模块。RoboDoc 能帮您将文档按照这样的树型结构进行组织，实现的方式就是在头部中就进行这样的结构指定。

比如，您准备开发一个项目，目的是要实现一种新的语言，假设这种语言的名字为 D ，在这个项目中，有三个应用程序，一个预处理器、一个编译器和一个连接器，在编译器中又包含两个模块，分别是语法分析器和目标产生器，在语法分析器中又有好些个函数。

下面的三个头部就能够显示这样的树型结构：

#****h* D-Language/Compiler
# FUNCTION
#   The compiler takes a preprocessed source file and
#   turns it into an object file.
#***
#****h* D-Language/Linker
# FUNCTION
#   The linker module contains functions that scan a 
#   object file and build the executable.
#***
#****h* Compiler/Parser
# FUNCTION
#   The parser module contains functions that scan a 
#   preprocessed source file and build the syntax tree.
#***
#****f* Parser/ReadToken
# FUNCTION
#   ReadToken reads the next token from the input
#   file.
#***

当您在产生文档的时候使用了选项

--section

的时候， RoboDoc 就会根据这些信息产生出树型结构的文档。比如在 HTML 形式的文档中，段会使用根据级别的 < H1 >, < H2 >, < H3 > 进行标识，产生的文档样子会如下所示：

1. D-Language/Compiler
1.1 Compiler/Parser
1.1.1 Parser/ReadToken
2. D-Language/Linker

使用 RoboDoc 来产生文档

现在，假设我们已经使用了上面描述的格式准备了源代码，就要用 RoboDoc 来产生文档了。首先我们要做一些抉择，;-)

一个大文档还是多个小文档？

首先，RoboDoc 能够在三种模式下来使用：

multidoc: 在这种模式下，对所有的源文件都会产生一个单独的文档文件，而且所有文档文件的目录结构和源文件的目录结构会保持一致，文档的目录结构是源文件目录结构的一个映象，这个目录结构会自动的产生出来；
singledoc: 在这个模式下，所有的源文件被扫描以后，文档文件会被放在一个单独的文档文件中；
singlefile: 在这个模式下，仅仅扫描一个单独的文件，并且产生一个单独的文档文件；

multidoc

这个模式对于产生易于浏览的文档比较合适，比如是用于浏览器使用的很多的 HTML 格式的文档。这个模式需要下面的参数格式进行调用：

robodoc {--src source directory} {--doc document directory} {--multidoc} 
[other options]

还有一个很有用的参数是 --index ，这会针对每种头部类型产生一系列的索引文件。

singledoc

这个模式对于产生一个比较大的文档嵌入到其他的文档中去比较合适，或者可以将文档一下就发送出去。比如您产生了一个 RTF 格式的文档后，就可以将它嵌入到一个 WORD 文件中，调用的方式为：

robodoc {--src source directory} {--doc document file without extension}
{--singledoc} [other options]

singlefile

这个模式不是太有用处，主要是可以使用在调试的时候，其调用的方式为：

robodoc {--src source file} {--doc document file} {--singlefile} [other options]

输出格式

另外一个选择就是您想得到什么格式的文档，现在被支持的文档格式如下表：

输出格式	得到该格式文档使用的选项
HTML	--html
RTF	--rtf
LaTEX	--latex
XML DocBook	--dbxml

RoboDoc 支持的选项

下面是 Robodoc 支持的一些选项及其功能的列表：

选项	功能
-c	Show the copyright message.
--cmode	Use ANSI C grammar in SOURCE items and use this for some syntax highlighting (HTML only).
--css	Use to content of the specified file to create the robodoc.css. The content of the file is copied into robodoc.css.
--dbxml	Generate documentation in XML DocBook format.
--doc	Define the path to the documentation directory or documentation file. A path can start with ./ or /. Do not use .. in the path. The documentation directory can be a subdirectory of the source directory, or be parallel to the source directory, however they can not be equal. So --src ./sources together with --doc ./documents is fine, but --src ./Everything together with --doc ./Everything is not.
--folds	Use fold marks to split a big document into smaller ones.
--html	Generate documentation in HTML format.
--internal	Also include headers marked internal.
--internalonly	Only include headers marked internal.
--index	Also create a master index file.
--lock	Per source file robodoc locks on the first headermarker it finds and will recognize only that particular headermarker for the remaining part of the file. In addition it locks on the first remark marker in each header and will recognize only that particular remark marker for the remaining part of the header.
--multidoc	Generate one document per source file, and copy the directory hierarchy.
--nosource	Do not include the SOURCE items.
--nodesc	Do not scan any subdirectories, scan only the top level directory of the source tree.
--rc	Use the specified file instead of robodoc.rc.
--rtf	Generate documentation in RTF format.
--sections	Create sections based on the module hierarchy.
--singledoc	Define the documentation directory or documentation file.
--singlefile	Generate a single document from a single file
--src	Define the path for the source directory or source file. The path can start with ./ or /. Do not use .. in the path.
--tabsize	Lets you specify the tabsize.
--toc	Add a table of contents. This works in multidoc mode as well as singledoc mode.
--latex	Generate documentation in LaTEX format.
--tell	ROBODoc tells you what steps it is taking.

配置文件

配置文件可以用来指定 RoboDoc 的行为，其配置文件的名称缺省为 robodoc.rc 。下面我们来讨论他的写法，请看下面的例子：

# Example robodoc.rc
#
items:
    NAME
    SYNOPSIS
    INPUTS
    OUTPUTS
    SIDE EFFECTS
    HISTORY
    BUGS
ignore items:
    HISTORY
    BUGS
options:
    --src ./source
    --doc ./doc
    --html
    --multidoc
    --index
    --tabsize 8
headertypes:
    e  "Makefile Entries"  robo_mk_entries
    x  "System Tests"      robo_syst_tests
    q  Queries             robo_queries
ignore files:
    README
    CVS
    *.bak
    *~
    test_*

整个配置文件分成几个部分，每个部分由一个名称开头，后面紧跟一个冒号。在这个例子中有五个部分： items, ignore items, options, header types 和 ignore files 。每个部分有一系列的值，每个值的前面至少有一个空格。

items 部分

指定可以识别的条的名字。每个条的名字能包含一个或多个单词，但是必须是大写字母。每一行上写一个条的名字。对于多个单词的条的名字，您不必在上面加上引号。

如果您没有给 items 部分，那么 RoboDoc 会使用缺省的条名称。如果您指定了 items 部分，那么只有列出来的这些条名称会被识别，不过 SOURCE 是一个例外，它总是能被识别。

ingore items 部分

这个部分列出来的条名称在文档产生的时候，相应的条都会被忽略。

options 部分

这个部分可以指定您想要指定的命令行选项。

headertypes 部分

在这个部分您可以指定您自己的头部类型，这些头部类型会被加入到现有的头部类型中去。指定一个新的头部类型，您需要指定三个参数：一个是用来表示这个头部类型的字母，这种头部类型的名称（用于产生索引），然后是这种类型的索引被存储的文件的名字。如果您新定义的头部识别字符已经被用过了，那么原来的定义将被覆盖掉。

ignore files 部分

这个部分您可以指定哪些文件不需要 RoboDoc 帮您处理，在指定的字符串中，您可以使用通配符 * 和 ? 。

命令行配置文件

缺省情况下， RoboDoc 会在当前目录中寻找 robodoc.rc 文件作为配置文件，但您也可以在命令行指定配置文件，选项为 --rc 。这样，您可以如下例一样方便的产生不同格式的文档：

robodoc --rc  htmlsingle.rc
robodoc --rc  rtfsingle.rc
robodoc --rc  htmlmulti.rc

例子

HTML 格式的例子

这样产生的文档能够在浏览器中使用，比如在 Mozilla 中。下面的例子会产生一个叫做 HDocs/masterindex.html 的文档加上很多从源代码中产生出来的小文档：

robodoc --src ./Source --doc ./HDocs --multidoc --index --html

RTF 格式的例子

下面的例子会产生一个名为 api.rtf 的文档，可以在 Word 中使用：

robodoc --src ./Source --doc api --singledoc --rtf --sections

缺省情况下产生的 RTF 文档非常朴素，您可以通过在一个 Word 一样的编辑器中处理一下。

LaTEX 格式的例子

下面的例子会产生名为 api.dvi 的文档：

robodoc --src ./Source --doc api --singledoc --latex --sections
latex api.tex
latex api.tex
makeindex api.idx
latex api.tex
xdvi api.dvi

您可以从这个 DVI 文件中的到您想要的 PS 或者 PDF 格式的文档。

XML DocBook 格式的例子

robodoc --src ./Source --doc api --singledoc --dbxml --sections
xmlto html api.xml

高级功能

不要 SOURCE

使用原始的 HTML 和 LaTEX 代码

请看下面的例子：

/****m* pipe/pipetest
 * NAME
 *   pipetest
 * NAME
 *   Simple header to show "piping" features in items. 
 * EXAMPLE
 *   Only "pipes" which match selected output style are picked up. 
 *   |html <CENTER>This will be included in <B>HTML</B> output.</CENTER>
 *   |latex \centerline{This will be included in \LaTeX output}
 *   Space is mandatory following the pipe marker. The following is not a
 *   valid pipe marker:
 *   |html<B>Moi!</B>
 *   You should see an equation on the following line:
 *   |html y = x^2 (sorry, plain HTML is not very powerful)
 *   |latex \centerline{$y = x^2$}
 *   How does this look like?
 *   Here comes a multi-line equation array:
 *    |latex \begin{eqnarray}
 *    |latex \frac{\partial u}{\partial \tau} & = & D_u {\nabla}^2 u + 
 *    |latex \frac{1}{\epsilon}
 *    |latex \left ( \hat{u}-{\hat{u}}^2-f\, {v} \, \frac{\hat{u}-q}{\hat{u}+q}
 *    |latex \right ) \; ,  \label{diffspot:1} \\
 *    |latex \frac{\partial v}{\partial \tau} & = & \hat{u}-v \; ,  
 *    |latex \label{diffspot:2} \\
 *    |latex \frac{\partial r}{\partial \tau} & = & D_r {\nabla}^2 r \; .
 *    |latex \label{diffspAot:3}
 *    |latex \end{eqnarray}
 *    |html <I>TODO: write this in html</I>
 *   End of the example.
 ******
 */

链接到外部文档

下面是可以识别的用于链接到外部文档的方式：

   使用语法        转换成的 HTML 的形式
   href:body      <a href="body">body</A>
   file:/body     <a href="file:/body">file:/body</A>
   mailto:body    <a href="mailto:body">body</A>
   http://body    <a href="http://body">http://body</A>
   image:body     <image src<nop>="body">

提供的 Anchor

如果您想从一个外部文档链接到 RoboDoc 产生的文档中来，您就必须了解到在产生的文档中，都有一些什么样的文件名和每个文件中都有一些什么名称的 Anchor 。

RoboDoc 会为每个头部产生一个可以用于这样的目的的 Anchor，其名称是该头部的名称和模块名通过一些变换得到的，比如头部 Analyser/RB_ToBeAdded 会被转换为 Analyser2fRB5fToBeAdded 。其中斜杠和下划线都转换成为了它们的 16 进制的 ASCII 码。

Updated: 2004-06-12

Index