Date: Tue, 21 Aug 2012 20:54:36 +0100 From: "Simon L. B. Nielsen" <simon@FreeBSD.org> To: Gabor Kovesdan <gabor@FreeBSD.org> Cc: doceng@FreeBSD.org, doc@FreeBSD.org, www@FreeBSD.org Subject: Re: [CALL FOR REVIEW] doc and www converted to XML Message-ID: <1FDFD92B-36C6-4BE8-88FB-8C6D2A759954@FreeBSD.org> In-Reply-To: <50326A70.5020009@FreeBSD.org> References: <50326A70.5020009@FreeBSD.org>
index | next in thread | previous in thread | raw e-mail
On 20 Aug 2012, at 17:48, Gabor Kovesdan <gabor@FreeBSD.org> wrote: > 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. We really should fix this (the magic of en/htdocs building other languages too etc; DESTDIR not meaning what it does in base etc.), but that can be done later. > 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 I looked at a random page, and the identation for the header is a bit funny. Is that just an artifact of an automatic conversion or? Example: http://svnweb.freebsd.org/doc/projects/sgml2xml/en_US.ISO8859-1/htdocs/logo.sgml?revision=39396&view=markup > - - 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 Yay. tidy die die die :-). > - - 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 If you are going to change it, could you please change it to use svn and with a REPO path we can set from the web build wrapper? I would REALLY like if we could get the web build fixed to never try to get data from the internet. > - - 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 Do that mean that the current build dependencies are unchanged? > 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. Sure, I think it makes a lot of sense to do that separately later. Smaller steps makes it much simpler to test verify etc. > Thanks in advance for your review. Thanks for working on this! We were talking on doing this when I was a new doc committer :-). PS. sorry for not following up on the previous mails wrt. XHTML etc... limited time unfortunately. -- Simon L. B. Nielsenhelp
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1FDFD92B-36C6-4BE8-88FB-8C6D2A759954>