Date: Mon, 04 Feb 2013 10:25:22 +0100 From: Gabor Kovesdan <gabor@FreeBSD.org> To: Giorgos Keramidas <keramida@FreeBSD.org> Cc: doc@FreeBSD.org Subject: Re: RFC: Dealing with version-specific docs Message-ID: <510F7E82.9000708@FreeBSD.org> In-Reply-To: <20130204041717.GA68155@kobe> References: <51065CFC.5090803@FreeBSD.org> <20130204041717.GA68155@kobe>
next in thread | previous in thread | raw e-mail | index | archive | help
Em 04-02-2013 05:17, Giorgos Keramidas escreveu: > I like the use of os= attributes, but I feel a bit at odds with the > requirement to duplicate version information in the XML attribute*and* > the contained text, e.g.: > > <para os="freebsd8">To do foobar on &os; 8.X, type bar.</para> > > <para os="freebsd9">To do foobar on &os; 9.X, type baz.</para> > > We are typing version numbers twice here, and this introduces both the > possibility for error and the chance for missing important mismatches in > XML attributes vs. actual text. > > Is there any way we can avoid typing the version numbers twice? Theoretically, we could render the marked sections differently and then it would not require duplicated information. But in practice, this requires heavy customization of our build process. We have to customize different things: - The XSLT stylesheets used for XHTML output. This is quite easy, I can do it without problems. - Either we keep using Jade for PS/PDF generation and then we have to customize the DSSSL stylesheets. DSSSL is a dead and badly documented standard and I practically don't know anything about it so we need to find someone, who is willing to do it. It is not easy because it never became widely used and there is no free reference or documentation about it. It also raises the question whether it is worth investing time and effort in something that is so outdated. - Or we allow Java dependency just for the printed output formats (XHTML would still be generated without Java) and then we need to do the customizations in XSLT/XSL FO, which is much easier and I can do it myself. I mentioned these problems at EuroBSDCon but people were quite reluctant about the Java dependency even though the XHTML part would still work without Java. I think that I have to raise this issue again. I've been working on improving the doc tree to use up to date and better standards than the earlier ones and now I have a branch with some important updates. I've maintained compatibility with Jade but sooner or later we'll have to move away from it. The trivial way is using Fop (a Java-based XSL FO renderer), which all other open source projects do that use XML-based documentation. Some people suggested generating PDF from XHTML which imho is a bad option since XHTML is not a paper-oriented markup so we loose features in that way, so I don't believe in its success and I'm not really willing to work on botches. Now I'll bring the tree technologically up to date until the point where we can avoid Java but then we will have to choose how to go beyond. Gabor
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?510F7E82.9000708>