Date: Mon, 20 Aug 2012 18:48:48 +0200 From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc@FreeBSD.org, www@FreeBSD.org Cc: doceng@FreeBSD.org Subject: [CALL FOR REVIEW] doc and www converted to XML Message-ID: <50326A70.5020009@FreeBSD.org>
next in thread | raw e-mail | index | archive | help
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Dear Folks, I'm glad to announce that the first milestone of the XML migration is available for review in the projects/sgml2xml branch. To check it out, run the following: svn co http://svn.freebsd.org/doc/projects/sgml2xml sgml2xml The build process - from the end user perspective - works in the same way. In short, use make all at the proper place, to build only web, run make all WEB_ONLY=yes in the htdocs dir, etc. Then use make install with DESTDIR defined to install files to the proper place. A rendered version of the website is available here: http://people.freebsd.org/~gabor/xmlweb/data/ For the documentation, you can directly go to: http://people.freebsd.org/~gabor/xmlweb/data/doc/ This branch includes the following changes: - - Documentation is updated from DocBook 4.1/SGML to DocBook 4.2/XML - - Webpages are updated from HTML 4.01 Transitional to XHTML 1.0 Transitional - - Static webpages are now processed by XSLT behind the scenes - - Webpages are now built with less cycles; tidy has been removed and the date processing is now done by XSLT - - Generated webpages are now actually valid (they did not use to be) - - All XSLT stylesheets now pull in a main XSLT, which reduces duplicated markup - - Site map and index are converted to an XML format with an XSLT transformation that generates the output - - For docs, there is now only one entity set for both articles and books - - Some trademark/legalnotice entities have been merged to a cohesive single entity file - - Untranslated entity sets are now always pulled in from the English tree instead of redundant copies - - The base and enbase entities are already automatically generated so remove inline definitions from individual files - - Fetch the LEGAL file via http instead of depending on CVS - - Convert id names to lowercase to avoid mixing different styles and for better readability - - All PSGML comments are removed since they are mostly useless As it has been discussed, the character entities will be dropped. This is still in progress but it is already a good moment for the rest to be reviewed since it is a big change that needs proper review and testing. At the same time, this also means that it is not easy to maintain such a big changeset in a branch since merging so many files is really time-consuming so it would be beneficial not to spend more time with merging this back than necessary. I would like to ask you to review this changeset and let me know any type of problems you encounter or any type of doubts you have. It would be nice if all translator projects could check their translations to see if there is any locale-specific problem. Despite the big quantity of the changes, the modernization process of the doc tree is not complete with this change. First, we still use Jade and DSSSL to generate output, which is an SGML tool and works because of the fact that XML is a subset of SGML. But it does not really benefit of XML technologies and the DocBook DSSSL stylesheets are quite obsolete. In a second step, we should migrate to an XSL(T)-based toolset. Secondly, the DocBook 4.2 schema is quite old, the current DocBook version is 5.0. But 4.2 is the first XML version and it still works well with the old DSSSL stylesheets so this was a safe migration path that gives us more time for the migration and for QA. Once this branch is merged back, the migration of the toolset will be started in another branch. Thanks in advance for your review. Regards, Gabor (On behalf of doceng@) -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAlAyanAACgkQkC3QTyNzprGWhACfVzoyEb/WvXkiFn3cGIaCdEdU GzIAoL9AUJzc8WtNPyxH6PZnNKbvwUXA =i60i -----END PGP SIGNATURE-----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?50326A70.5020009>