openpkg-packages/odoc/odoc.8

.TH ODOC 8 "July 17, 2005" "" "OpenPKG"
.SH NAME
\fBodoc \fP- create index.html doc files
.SH SYNOPSIS
.nf
.fam C
\fB%{l_odoc}\fP [<opts>] %{SOURCE %{name}.spec}
\fBodoc\fP -s
.fam T
.fi
.SH DESCRIPTION
\fBodoc\fP helps to create index.html files
.SH OPTIONS
.TP
.B
-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
.TP
.B
-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
.TP
.B
-i
insert text section (see -w) from odoc.inf
.TP
.B
-I file
specify location of odoc.inf (default: %{SOURCE odoc.inf})
.TP
.B
-r file
insert content of <file> at working location
.TP
.B
-l dir
insert directory list at working location only basename, looks in
odoc.inf (see -w) for additional per file info
.TP
.B
-L
create symlinks in %prefix/doc/<pkg> that point
to ../../share/<pkg>/{docs,examples}, when those dirs exist
.TP
.B
-h url
adds link "home"-><url>
.TP
.B
-o file
name of output file (default: tmpl from -t)
.TP
.B
-R
prepend $RPM_BUILD_ROOT on paths that start with %prefix
.TP
.B
-a
-t odoc_aux -w adoc -l %prefix/doc/<pkg> -LR \
-h ../../../..%prefix/share/openpkg/docs/index.html \
-o %prefix/doc/<pkg>/index.html"
.TP
.B
-m
-t odoc_man -w mdoc -l %prefix/share/<pkg>/docs -R \
-o %prefix/share/<pkg>/docs/index.html"
.TP
.B
-e
-t odoc_ex -w edoc -l %prefix/share/<pkg>/examples -R \
-o %prefix/share/<pkg>/examples/index.html
.TP
.B
-s
-t odoc_sum -w sdoc \
-o %prefix/share/openpkg/docs/index.html
create summary info in %prefix/share/openpkg/docs
.TP
.B
-v
verbose
.TP
.B
-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'
.RE
.PP
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 \fBodoc\fP 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.
.SH FILES
odoc.inf
.SH EXAMPLES
.nf
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>
.PP
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
.PP
"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'.
.SH AUTHOR
Matthias Kurz <mk@openpkg.net>