ODOC(8)

NAME
odoc - create index.html doc files

SYNOPSIS
%{l_odoc} [<opts>] %{SOURCE %{name}.spec}
odoc -s

DESCRIPTION
odoc helps to create index.html files

OPTIONS

-t tmpl
    uses the given file as template html the special names odoc_aux, odoc_man, odoc_ex and odoc_sum are used to generate standard templates for auxilliary, mandatory and summary documentation

-w tag
    specify "working location" in output file (searches for <!--!tag-->) it is also used by some options to identify a section with additional info in odoc.inf

-i  insert text section (see -w) from odoc.inf

-I file
    specify location of odoc.inf (default: %{SOURCE odoc.inf})

-r file
    insert content of <file> at working location

-l dir
    insert directory list at working location only basename, looks in odoc.inf (see -w) for additional per file info

-L  create symlinks in %prefix/doc/<pkg> that point to ../../share/<pkg>/{docs,examples}, when those dirs exist

-h url
    adds link "home"-><url>

-o file
    name of output file (default: tmpl from -t)

-R  prepend $RPM_BUILD_ROOT on paths that start with %prefix

-a  -t odoc_aux -w adoc -l %prefix/doc/<pkg> -LR -h ../../../..%prefix/share/openpkg/docs/index.html -o %prefix/doc/<pkg>/index.html"

-m  -t odoc_man -w mdoc -l %prefix/share/<pkg>/docs -R -o %prefix/share/<pkg>/docs/index.html"

-e  -t odoc_ex -w edoc -l %prefix/share/<pkg>/examples -R -o %prefix/share/<pkg>/examples/index.html

-s  -t odoc_sum -w sdoc -o %prefix/share/openpkg/docs/index.html create summary info in %prefix/share/openpkg/docs

-v  verbose

-F  calls the command "false"; this way it is possible to detect whether a "real" odoc is installed or just a stub, that calls 'true'

The options -a, -m and -e can be used together and result in three index.html files. The -a, -m, -e and -s options are mutually exclusive to every other option except -v. %{SOURCE odoc.inf} can hold additional info for odoc operations. The file consists of sections, that start with <section id="tag"> and end with </section>. To access the docs over an apache httpd add the line "include %prefix/share/openpkg/docs/odoc.apache" to httpd.conf.

FILES
odoc.inf

EXAMPLES
sample odoc.inf:
----------------
<section id="tag">
This is <b>html</b> text to be included with -i.<br>
And this is a second line.
<!--!canAddLaterMoreHere-->
</section>
<section id="anotherTag">
file1 - description of file1 (also <b>html</b>)
file5 : description of file5
</section>

sample commands:
----------------
mv mdocs/*    $RPM_BUILD_ROOT%{l_prefix}/share/pkg/docs
mv examples/* $RPM_BUILD_ROOT%{l_prefix}/share/pkg/examples
if   %{l_odoc} -F
then echo "WARNING: no aux docs will be packaged" 1>&2
else mv adocs/* $RPM_BUILD_ROOT%{l_docdir}/pkg
     %{l_odoc} -ame %{SOURCE %{name}.spec}
     %{l_odoc} -w arem -i tag -t $RPM_BUILD_ROOT%{l_docdir}/pkg/index.html
fi

"arem" is one insert point that is put in the standard template odoc_aux
(similiar tags "mrem", "erem" and "srem" are in odoc_man, odoc_ex and
odoc_sum).
For the example above "odoc.inf" has to have a section "arem" and can
have the sections "adoc", "mdoc" and "edoc" with informations that are
selected using the filenames.
The command %{l_odoc} -F checks, whether %{l_odoc} is just a stub that
calls 'true'.

AUTHOR
Matthias Kurz <mk@openpkg.net>