From owner-freebsd-doc@FreeBSD.ORG Tue Aug 21 19:54:46 2012 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 934B81065670; Tue, 21 Aug 2012 19:54:46 +0000 (UTC) (envelope-from simon@FreeBSD.org) Received: from emx.nitro.dk (leto.nitro.dk [178.63.52.6]) by mx1.freebsd.org (Postfix) with ESMTP id DF9688FC23; Tue, 21 Aug 2012 19:54:45 +0000 (UTC) Received: from mailscan.leto.nitro.dk (mailscan.leto.nitro.dk [127.0.1.4]) by emx.nitro.dk (Postfix) with ESMTP id BCFE72B753D; Tue, 21 Aug 2012 19:54:44 +0000 (UTC) Received: from emx.nitro.dk ([127.0.1.2]) by mailscan.leto.nitro.dk (mailscan.leto.nitro.dk [127.0.1.4]) (amavisd-new, port 10024) with LMTP id KPPDsfhmSW_A; Tue, 21 Aug 2012 19:54:38 +0000 (UTC) Received: from [192.168.4.24] (unknown [89.100.2.68]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (No client certificate requested) by emx.nitro.dk (Postfix) with ESMTPSA id D78CD2B7532; Tue, 21 Aug 2012 19:54:37 +0000 (UTC) Content-Type: text/plain; charset=iso-8859-1 Mime-Version: 1.0 (Mac OS X Mail 6.0 \(1485\)) From: "Simon L. B. Nielsen" In-Reply-To: <50326A70.5020009@FreeBSD.org> Date: Tue, 21 Aug 2012 20:54:36 +0100 Content-Transfer-Encoding: quoted-printable Message-Id: <1FDFD92B-36C6-4BE8-88FB-8C6D2A759954@FreeBSD.org> References: <50326A70.5020009@FreeBSD.org> To: Gabor Kovesdan X-Mailer: Apple Mail (2.1485) Cc: doceng@FreeBSD.org, doc@FreeBSD.org, www@FreeBSD.org Subject: Re: [CALL FOR REVIEW] doc and www converted to XML X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 21 Aug 2012 19:54:46 -0000 On 20 Aug 2012, at 17:48, Gabor Kovesdan wrote: > Dear Folks, >=20 > 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: >=20 > svn co http://svn.freebsd.org/doc/projects/sgml2xml sgml2xml >=20 > 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=3Dyes 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/ >=20 > 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/log= o.sgml?revision=3D39396&view=3Dmarkup > - - 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 >=20 > 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. >=20 > 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. --=20 Simon L. B. Nielsen