devdoc [-t dir] [-o dir] [-f format] [-b dir] [-C options] dirnames filenames
devdoc --help|--version

devdoc takes files in LaTeX markup language or directories with that files and transforms them into html or man format. The main part is done with latex2man(1) script. Transition is performed with basic perl, thus requiring lean environment. Not entire LaTeX is supported, but just subset of it, described in latex2man(1) doc.

Utility prints names of generated files to stdout. Log files during the generation are saved into ./var/log/.

-t html-template

Use directory html-template as template for generated html pages. Its basic effect:

-

All files from html-template are copied to output directory for html pages, var/html/ by default.

-

Each html page is constructed as concatenation of file up.template in html-template directory, the generated content from LaTeX source, and the file down.template in html-template directory.

So generated html pages can be widely customised besides CSS.

For other formats besides HTML option takes no effect.

-o output-dir

Change the output directory. ./var/ is the default value.

For each format nested directory is created: html pages are saved into ./var/html/, man pages into ./var/man/. Additionaly, man pages are sorted by sections, as man database expects them: ./var/man/man1, ./var/man/man7, etc.

-f

Set up the format to generate. Possible values:

html

html pages, bundled together as site. They are generated with template and cross-linked.

man

classical man pages in troff format.

latex

output in tex, cleaned up from conditional latex2man code. Useful for further pdf generation by third-party tools.

txt

plain text, rendered from html with text browser, links by default. You may set up another browser with TEXT_BROWSER variable. Text browser must support -dump option for plain text generation.

pdf

render pdf output with native pdflatex tool. Name can be switched with PDFLATEX variable. This requires TeXLive or other LaTex distribution.

odt

render odt output: open document format, suitable for libreoffice. By default this is done with htlatex tool. Name can be switched with HTLATEX variable. This requires TeXLive or other LaTex distribution.

Several values can be given at once:

devdoc -f html,man srcdoc/

Default formats: html,man

-b base-dir

Set up base directory for doc sources. By default, base directory equals to directory, given in command line. If you change it, paths inside html pages will begin from new base. Example source layout:

srcdoc/proj/index.tex

srcdoc/proj/nested/something.tex

By default with the launch:

devdoc srcdoc/proj/

The result will be:

var/html/index.html

var/html/nested/something.html

With the option to change base directory:

devdoc -b srcdoc/ srcdoc/proj/

The result will be:

var/html/proj/index.html

var/html/proj/nested/something.html

-C options

Redirect string after the option -C to latex2man(1) option -C.

--version

Print version and exit with 0 code.

--help

Print short help description and exit with 0 code.

To render entire directory srcdoc with documentation sources into man and html:

    devdoc srcdoc/

Render single file:

    devdoc srcdoc/mydesc.tex

Render several directories:

    devdoc srcdoc/ anothersrc/

In case of rendering several directories, they will be cross-linked together by relative paths they have according to each other.

Use your own html template by location srcdoc/html-template/ to get nice linked site after html output:

    devdoc -t srcdoc/html-template/ srcdoc/

By default, output is saved into ./var/format/, for example, var/html/ or var/man/. Save output to another dir:

    devdoc -t srcdoc/html-template/ -o mydir/ srcdoc/

Render only man or only html:

    devdoc -f man  -t srcdoc/html-template/ srcdoc/
    devdoc -f html -t srcdoc/html-template/ srcdoc/

HTML template for the first command is not needed, but will not cause anything harmful.

To give explicit options for latex2man(1):

    devdoc -t srcdoc/html-template/ -C 'something' srcdoc/

That can be used for conditional latex code, supported by latex2man.

TEXT_BROWSER

variable contains the full path to console html browser, used for plain txt rendering. Not used besides txt format.
Default value: links

LATEX2MAN

variable can set up the path to latex2man script, used for doc rendering.
The variable is unset by default.

When variable is not set, inner version of latex2man is used, shipped with devdoc. It is named latex2man-devdoc not to intersect it with system script.

Do not change used version of latex2man, until you know what you are doing. Inner version may contain patches and change the behaviour without notice.

PDFLATEX

name of native LaTex tool to render pdf format. pdflatex by default. Variable does not concern other output formats besides pdf.

HTLATEX

name of LaTex tool to render odt format. htlatex by default. Variable does not concern other output formats besides odt.

The options from this section are more exotic and less used.

-D number

The depth of nested subdirectories, where source documentation files are searched. The default value is 10. Allowed range is between 0 and 1000.

latex2man(1), pdflatex(1), htlatex(1)