Making docs

[Giorgos Keramidas]

On 2007-07-01 15:27, Zbigniew Komarnicki <cblasius at gmail.com> wrote:
> Hello!
>
> I want to create documentation in FreeBSD. I read this article:
> http://www.onlamp.com/pub/a/bsd/2001/02/08/Big_Scary_Daemons.html
> then I compile and I obtain the following error:

You know we regularly re-build the documentation from the CVS repository
and publish the resulting documents online, right?  If you are not
really interested in contributing patches to the docs, then it may be a
little easier for you to just download the pre-built versions :)

Having said that, we could always use some more help with the current
documentation, so if you are trying to learn about the build process of
the documentation to help us improve the existing documents, you are
certainly more than welcome to help in any way you want!

> ===> books/pmake (install)
> /bin/rm -f docbook.css
> /bin/cat /usr/doc/share/misc/docbook.css > docbook.css
> Index is disabled or no index to generate.
> /usr/bin/env SP_ENCODING=ISO-8859-1 /usr/local/bin/jade -V
> html-manifest -ioutput.html -d /usr/doc/share/sgml/default.dsl -ifreebsd.urls.absolute
> -V %generate-legalnotice-link% -ioutput.html.images   -D /usr/doc/en_US.ISO8859-1/books/pmake/..
> /../../share/images/books/pmake -D /usr/obj/usr/doc/en_US.ISO8859-1/books/pmake -c
> /usr/doc/en_US.ISO8859-1/share/sgml/catalog -c /usr/doc/share/sgml/catalog -c
> /usr/local/share/sgml/docbook/dsssl/modular/catalog -c /usr/local/share/sgml/iso8879/catalog
> -c /usr/local/share/sgml/jade/catalog -c /usr/local/share/sgml/catalog.ports -t
> sgml /usr/doc/en_US.ISO8859-1/books/pmake/book.sgml
> /usr/local/bin/tidy -wrap 90 -m -raw -preserve -f /dev/null -asxml
> $(/usr/bin/xargs < HTML.manifest)
> *** Error code 1 (ignored)
> install -C  -o root -g wheel -m 444 $(/usr/bin/xargs <
> HTML.manifest) /usr/share/doc/en_US.ISO8859-1/books/pmake
> install -C  -o root -g wheel -m 444
> docbook.css /usr/share/doc/en_US.ISO8859-1/books/pmake
>
> What this error "*** Error code 1 (ignored)" means?

tidy(1) typically fails with a non-zero error code for things which we
are not really interested to fix, or are plainly harmless.  This is why
the Makefile which calls tidy precedes it with a dash '-' to ignore
errors from tidy's invocation.  The make(1) utility catches the non-zero
error status, and notifies you that it ignored it.  Most of the time,
it's relatively safe to ignore this error code.

> I also would like to ask you how to create PDF document, not only
> HTML? What command I should use to obtain PDF handbook, for example,
> because I want to print it?

First of all, you have to install the textproc/docproj-jadetex port, to
get the jadetex utility.

Then you can build a PDF version of any article or book with:

    $ cd doc/en_US.ISO8859-1/articles/formatting-media
    $ make FORMATS=pdf

the ${FORMATS} option controls which output format will be produced by
the make infrastructure of the documentation.  Other available format
options are:

    FORMATS=html               Single-file HTML output

    FORMATS=html-split         Multiple-file HTML output

    FORMATS=txt                Single-file plain text output

    FORMATS=ps                 Single-file PostScript output

    etc.

These options and other useful stuff about the build infrastructure of
the FreeBSD documentation set are described in the "FreeBSD
Documentation Project Primer for New Contributors" at:

    http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/fdp-primer/

Have fun building your own docs :-)

Regards,
Giorgos