----Security_Multipart(Wed_Feb__1_06_22_28_2006_483)--
Content-Type: Text/Plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

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

 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.

 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.

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

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

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

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

 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.

 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.

 Not so concrete but above are my thoughts at this moment.
 I do not deny more macroscopic point such as whether we should
 continue to use XML or not, but I think such discussion does not
 work without other promising candidates and rationale, and
 very time-consuming.  So I think it is worth while to spend time
 on specifically sorting out what we are trouble in and
 what we can improve from practical point of view, not from
 which tool should be used.

--
| Hiroki SATO

----Security_Multipart(Wed_Feb__1_06_22_28_2006_483)--
Content-Type: application/pgp-signature
Content-Transfer-Encoding: 7bit

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (FreeBSD)

iD8DBQBD39UUTyzT2CeTzy0RAgwOAJsG+zCttkFYFOhZ1l/cTGASLolxGACg1fYu
0YosrtffeRZFjggl2Ad3Ma0=
=2COi
-----END PGP SIGNATURE-----

----Security_Multipart(Wed_Feb__1_06_22_28_2006_483)----