Subject: Re: simplifying htdocs build procedure (long term)
To: None <>
From: Jan Schaumann <>
List: netbsd-docs
Date: 02/02/2006 08:41:00
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Hiroki Sato <> wrote:
>  Okay, then let us sort out our rough plan first.
>  I think points of contention so far are the following:

[many good points snipped]

>  Anyway, the primary one is we feel we do not enjoy the benefit
>  from the XML conversion relative to the complex structure very
>  much since it raises the hurdle of document writing.  However,
>  this complexity is caused by simple conversion from .html to
>  .xml, not by XML itself.

Very true indeed!

>  Also, for webpages we should handle reusable information
>  in another way.  Specifically, for example, news items can
>  be used from multiple pages but stored in a single file,
>  and it is better that when we edit that file the related
>  pages are also updated automatically.


>  So, to simplify the structure and take advantage of XML,
>  I would like to add the following changes to the whole htdocs/
>  directory:
>  - Convert Document/* documents to "book" form, which is used
>    in NetBSD Guide.  The scattered small files are difficult
>    to manage as mentioned earlier.  Manually handling navigation
>    link, table of contents, index, and so on is a nightmare.

Well, I think we should try to integrate as much as we can from
htdocs/Documentation into the NetBSD Guide, which is already in the
proper format.

>  - Move reusable information to XML database as possible.  For
>    example, unifying management of the project news items in
>    htdocs/share/db/news.xml, and in other pages, pull the items
>    from it.  Format of news.xml can be more straightforward for
>    average users who are not familiar with XML.

This will be most useful.  I imagine we have different news items with
different roles that we can then pull in on different pages by just
saying ``include all news of type foo''.

>  - Add capability to generate printable formats such as PostScript
>    and PDF from webpages, too.

As others mentioned, I think this is somewhat lower priority.  If we get
this as a side-effect of all the other changes, great.

>  - Eliminate extra packages from meta-pkgs/netbsd-{doc,doc-print,www}
>    and restructure them into ones for TXT, HTML, and PDF.

Yes.  I think we should see if we can eliminate the dependency on X11
headers/libs, which, AFAIK, are only needed to create the image maps of
locations of developers.

I once set up a google map with the locations.  That had the advantage
of not needing X11 and in general looking nicer, but has the
disadvantage that (a) it's offsite and we rely on another commercial
company to provide the service and (b) it provides for such detailed
zooming in that it might make developers uncomfortable to provide

(b) could easily be dealt with, since it's the developers decision of
how much precision they provide, but I think (a) might be a drawback.

>  Also, web design is another discussion topic independent
>  from the build infrastructure.  Hubert suggests adding navigation
>  link to our pages, for example, but it is not difficult to add it
>  technically.  If you have ideas for improving web design, I would
>  like to know them.

I think this, too, can be deal with when we have made progress and
simplified the current process.  One step at a time. :-)

If you have concrete ideas on how to get these improvements started, I'd
be all in favor of creating a branch of htdocs and working it out.


Wenn ich tot bin, mir soll mal Einer mit Auferstehung oder so
kommen, ich hau ihm eine rein! (Anonym)

Content-Type: application/pgp-signature
Content-Disposition: inline

Version: GnuPG v1.4.1 (NetBSD)