Hiroki Sato <hrs@NetBSD.org> writes:

> Jan Schaumann <jschauma@netmeister.org> wrote
>   in <20060130133517.GA21484@netmeister.org>:
>
> js> I agree that this is a good idea, but I'd suggest that we first make a
> js> decision which steps to take, then branch.  If you already have precise
> js> ideas, I'd say post them here and then go ahead and create a branch.
>
>  Okay, then let us sort out our rough plan first.
>
>  I think points of contention so far are the following:
>
>  * building infrastructure/writer issue
>
>    - keep consistent layout with less effort
>    - be able to propagate global changes without editing multiple files
>    - be able to typeset with fewer tools as possible
>    - should be easy enough to edit the contents
>    - documentation for writing webpages
>
>  * web design:
>
>    - links for easy navigation
>
>  * others
>
>    - minimal impact to mirrors

All agreed.

>  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.  Benefits from XML is that it is
>  possible to put a structure to the documents.  For example,
>  we have a lot of scattered files in Documentation/Hardware now,
>  but these are very difficult to manage.  Even if we finish
>  to convert each of them to .xml individually, we get nothing from
>  it.

True.

>  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.

I think we can move some documents to the newly created NetBSD
Internals Guide. Three that come to my mind are elf.xml, non-exec.xml
and lazyfpu.xml.

>  - 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.

Yes, this seems a nice idea.

>  - Separate layout/contents (especially in Ports) for more
>    consistent layout.  This can be realized by putting a file
>    for layout definition and files for contents for each
>    architecture.  This helps simplifying editing the port pages.
>
>  - Add validation capability using DTD.

This should be a priority. As the NetBSD project really appreciates
standards (heh) we should be able to produce W3C compliant html
files.

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

Ok, but lower priority.

>  - Eliminate extra packages from meta-pkgs/netbsd-{doc,doc-print,www}
>    and restructure them into ones for TXT, HTML, and PDF.
>
>  Immediate achievements we can get from these changes are
>  reduction of the number of the source files and where
>  we have to edit when we want to change a content becomes clear.
>  Basically no content change will be involved.
>  If you all agree to make a branch, I am ready to work on them.

Like I said on my previous email, I agree on a branch.

>  However, rebuilding/regeneration problem cannot be solved completely
>  in the current structure (committing .html files to the CVS repo).
>  I think we should consider building the htdocs/ directory on
>  a box periodically and put out the resulting files instead of
>  importing them into the CVS repo.  This affects our WWW mirrors;
>  mirror admins need to change the fetch method.  I would like your
>  comments on this topic.

Some points:

* If the tools didn't need X11, then we could put it on the NetBSD build
  boxes, but since they do, we need another solution.

* Petra pointed out that we could create another dir in our cvs tree,
  but this still has the problem of generated files under CVS control
  (which is sub-optimal IMHO).

* Relying on a developer to do the regen is sub-optimal too.

How does FreeBSD do it ?

-- 
Rui Paulo - rpaulo@fnop.net