about HTML-book maker

[Giorgos Keramidas]

On Thu, 5 Mar 2009 19:02:25 +0800, Michael <wxiluo at gmail.com> wrote:
> Dear FreeBSD handbook managers,
>
> I set up a blog about my stories about using FreeBSD to share my
> experience. But editing posts is my biggest problem.  I'd like to make
> a HTML book page like the handbook of FreeBSD.  How could you make so
> nice HTML book page? Using software? What is it?

Hi Michael,

If all you are looking for is a blog-like web application, then the
build infrastructure of our documentation may not be the best thing for
you.  Our online documentation contains *static* HTML pages, so there is
no support for some of the more advanced features of blog software, like
comments, trackback links, user authentication for recurring visitors,
page view statistics, and so on.

With that in mind, and if you really *do* want to use something like our
documentation build tools, I agree with what Manolis wrote:

  On Thu, 05 Mar 2009 15:18:29 +0200, Manolis Kiagias <sonic2000gr at gmail.com> wrote:
  > Hello Michael,
  >
  > Indeed, we are using some tools to create the handbook. We are glad
  > you like the results ;)
  >
  > Generally you would need to install the textproc/docproj-jadetex port
  >
  > For details on using this, please read the fdp-primer here:
  >
  > http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
  >
  > Generally, it would be much easier if you start by installing the
  > software and using it to compile the FreeBSD documentation first.
  > You can then easily pick up a ready e.g. article and use it as a
  > stub to create your own.  This is not really a difficult process.
  >
  > I'll be glad to help you on your first steps, just email me directly
  > with your questions.

One of the most important details about the build tools of our online
documentation is that they are freely available online.  You can copy
and reuse the build tools directly from our CVS repository.  All the
`Makefile' files in the source of the `doc/' tree are easily accessible
online through:

  http://cvsweb.FreeBSD.org/doc/

Setting up a personal site that uses a similar build toolchain is not
very difficult, but it does take a certain level of familiarity with the
BSD make(1) utility.  As Manolis pointed out, one of the ways to get
acquainted with the way the doc/ build system works is to try and hack
together a small article of your own and attach it to the normal build
of the FreeBSD documentation.  Once you get past that obstacle, you can
start reading about the files in `doc/share/mk' and other `doc/share'
sub-directories.  This will let you know how to customize the look and
feel of the site; the shared images used in article and book pages; the
trademarks, logos and other repeatedly occurring text parts; and so on...

As Manolis wrote, if you have questions about how our `doc/' build
works, you can either email personally one of the people who can help,
or you can email the freebsd-doc mailing list asking any questions you
have come up with.

Even more importantly, if you start using our documentation build tools
and you like what you see, you are more than welcome to join the FreeBSD
documentation team and help us improve, extend, or write entirely new
parts of the FreeBSD documentation.  We can always use as much help as
we can get :-)

HTH,
Giorgos