[Cu-wireless] ETX Protocol Spec

[Chase Phillips]

On Sun, 18 Apr 2004, David Young wrote:

> Neat.  I would be pleased to see how the other documents are converted
> to DocBook, too.  All the latest docs are in under cuw/trunk/doc/local/
> in Subversion.
>
> A few questions:
>
>     Is there a target for manual pages with the macro set described
>     in mdoc(7)?

I've had bad luck trying this.  If anyone knows how to use xsltproc or
xmlto to convert one of the three DocBook XML files I've posted here into
a man page I'm interested to learn as well.  (A common error I get with
these two methods is "No refentry elements!"  Maybe I'm doing something
wrong on my end?)

>     You said that it was lots of work setting up your computer to render
>     PDF/text/HTML from DocBook.  What programs will we need to install?

On a Red Hat machine a tool like up2date or apt-get is useful to fetch
some main packages (since they'll also grab those packages' dependencies).
The following packages comprise the core of the "Authoring and Publishing"
subsystem in Red Hat-like systems:

  docbook-style-dsssl
  docbook-utils
  docbook-utils-pdf
  docbook-style-xsl
  linuxdoc-tools
  tetex
  tetex-afm
  xmlto
  tetex-xdvi
  xhtml1-dtds

I think another 5-10 packages are installed as dependencies specified by
these packages.  Additionally, I recommend installing the Linux
Documentation Project XSL and CSS stylesheets.  They can be found at

  http://my.core.com/~dhorton/docbook/tldp-xsl/

as referenced from

  http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html

To make nice-looking PDFs, Apache FOP is used, so that should be installed
as well.  (FOP relies on Java, hence Java must also be installed.)

My plan for non-Red Hat machines involved archiving and making available
all the source packages referenced by the RPMs listed above.

>     I am trying to keep the development environment pretty slim.
>     Just for example, we are *very* close to being able to cross-build
>     the C-U Wireless boot media using only the NetBSD host tools, which
>     compile and run on virtually every POSIX system.  I would like for
>     the docs likewise to be rendered to PDF/HTML/manual page/whatever
>     with a compact, well-defined set of document transform tools.

Cool that the SDK is so small!  I agree that is ideal.  The list of
software above (if every package is truly needed, which I think it is) may
not meet that goal if included, however.

We might consider sacrificing, say, FOP to drop the Java requirement, but
the problem I've had then is that the output of xmlto's PDF converter
doesn't have the same capabilities (like adding PDF bookmarks, or nice
layout within the PDF doc itself).

Perhaps we could output to the larger set of formats (PDF/HTML/manual
page/Text/whatever) just for the web site and include/reference some
subset of the core DocBook packages necessary to build the HTML/manual
page/Text locally so that the basic conversion tools are in place and the
developer can become accustomed to using the DocBook format/process?

Btw, is it correct to assume that the reason for wanting to add the
document transform tools environment to the SDK is because we want to
encourage others to write *new* documentation, not just convert existing
documentation?

Chase