Converting design doc(s) to HTML.
From: Karl Fogel <kfogel_at_red-bean.com>
Date: 2006-05-23 20:24:04 CEST
Our main design doc is currently in doc/design/*.xml. It consists of
I would like to convert it to a single HTML file, www/design.html. I
I have not committed the conversion, because maxb prefers that the doc remain
Below is the IRC transcript. I believe it lays out all the arguments
<kfogel> Last night I manually translated doc/design/*.xml into a
<kfogel> I know you guys were working on some changes to the XML
<maxb> kfogel: eek!
<kfogel> I think your patches should be portable (with
<maxb> Why? After all, we can compile the XML to a single HTML
<madan> I would prefer the single page html
<kfogel> maxb: "easily" is relative.
<maxb> kfogel: 'make html' isn't easy?
<kfogel> maxb: what if you don't have the tools installed?
<kfogel> maxb: a compile step is *always* a barrier.
<davidjames> I agree it's easier to maintain as an HTML document
<kfogel> And frankly, who reads that document in anything but HTML
<davidjames> Also, if it's in www/design.html, we can point users to
<maxb> These days, libxslt and the xsl stylesheets are packaged
<kfogel> I mean, what is the XML getting us here, except a) an
<kfogel> what davidjames said
<kfogel> maxb: I personally have had trouble building XML->HTML
<kfogel> This process is not as trivial as you are making it out
<kfogel> all the people I was looking for, in the same place
<kfogel> how nice
<madan> +1 from me, I dont see any specific use of xml... its
<madan> and all that makefile code to be maintianed.... yuk
<kfogel> madan: I applaud your obvious good taste! :-)
<maxb> I am opposed to HTML on the basis that it is far easier
<madan> so make it difficult to change the source doc?
<maxb> Also, on the basis that the having the design document
<kfogel> maxb: indeed, you will probably find that some of my
<kfogel> maxb: why is that "nice"?
<kfogel> What's the actual advantage?
* kfogel turns on all the fire hoses at once :-)
<sussman> fight, fight, fight!
* sussman grabs popcorn
<maxb> Because, we wish the people editing the design document
* madan ducks the crossfire
<kfogel> maxb: and, uh, how often does that happen?
<kfogel> In fact, who helps edit the design doc at all?
<maxb> No one, at present.
<kfogel> Has the thing not been sitting in stasis since roughly
<maxb> But, anything which helps train committers to help out
<kfogel> rooneg: sure! nothing wrong with a big party...
<kfogel> maxb: I highly doubt that the reason people do or don't
<kfogel> The design doc is different: the formatting overhead is
<kfogel> Here, let me put it this way maxb:
<maxb> I think the design doc is large enough that there is
<kfogel> If the design doc had been www/design.html when you
* kfogel plays his trump card
<maxb> And whilst I agree that there is the issue of learning
* maxb eyes hacking.html with a conspiratorial grin....
<kfogel> The trump card: I think that any argument claiming that
<maxb> I feel that that reasoning isn't quite true
<kfogel> clkao: hey there!
<maxb> For a very long time, it was in texinfo, with a toolchain
<kfogel> maxb: there's another step that the XML forces on us: we
<kfogel> We can't just commit a change and have it be visible.
<maxb> And, by the time I converted it, it was already so out of
<davidjames> There's no need to have a separate build step
<kfogel> Instead, the design docs -- which are very important --
<madan> may I add, that yesterday was the first time in 1.5 years
<madan> without distractions
<maxb> kfogel: I'm happy to set up regular builds on red-bean
<madan> maxb, its also difficult to edit
<kfogel> maxb: not a solution at all, as you well know
<maxb> And I'm also happy to improve the documentation
<madan> what are you planning to do about it
<kfogel> maxb: well, I've laid out my reasons.
<maxb> kfogel: "not a solution at all, as you well know" --- I
<kfogel> The reasons why that is not a good solution seem so
<kfogel> 1. another build process somewhere that can break, and
<maxb> I see this proposal as a technical regression for the
<kfogel> 2. the URL to the doc becomes at red-bean instead of
* heisenbug has quit ()
<kfogel> maxb: I am not persuaded at all by these fancy words :-).
<maxb> OK, let me put it another way: I object to adapting
<kfogel> Okay, I feel I've laid out all the reasons. I'm going to
<kfogel> I'm not sure what else to say :-).
<maxb> Well, could you at least air the issue on the list
<kfogel> I could, if you really want. But it seems like all the
<madan> maxb, why cant we just have it simpler!
<malcolmr> maxb: While I like Docbook and semantic markup over HTML
<maxb> No one previously has worked on that doc.
<kfogel> aren't you and madan working on it right now?
<kfogel> And, as I said before, I have several times sat down to
<madan> malcolmr had some comments on the build scripts... maybe
<malcolmr> I did?
<maxb> I'd like to have at least some small attempt to
<maxb> I agree: I don't find it a problem - so I may have
<kfogel> No. I mean, that's a nice thought, but many people here
<madan> malcolmr, about doc/tools/bin/find-xsl.py
<kfogel> I am not making this argument from ignorance, at least
<malcolmr> Oh that, just that it was broken on Gentoo. Max fixed it,
<malcolmr> (I don't even use Gentoo)
<kfogel> Under the current system, could you please send me a URL
<madan> yeah, he did
<kfogel> Pointing them to a prebuilt HTML page on red-bean is not
<malcolmr> kfogel: Bad example. I can send you such a URL, but your
<kfogel> The style will be different. Or, if we download the
* heisenbug (n=ggreif@p5494470B.dip.t-dialin.net) has joined #svn-dev
<maxb> But the only reason it can't be on tigris is because of a
<kfogel> maxb: so why is that a bad reason?
<kfogel> malcomr: these practicalities are what makes the world go
<malcolmr> Well, yes, I was just being precise :-)
* kfogel rolls eyes :-)
<davidjames> The issue with a prebuilt web page isn't that it's on
<davidjames> hacking.html is much bigger than design.html
<kfogel> good point
<davidjames> Imagine if we split up hacking.html into a set of XML
* kfogel names davidjames as new Ambassador to Maxb for the idea
* maxb eyes hacking.html with a conspiratorial grin, again.
<kfogel> Look, I didn't just wake up and decide I wanted HTML
<kfogel> But if I make them, what good will it do? I'll have to
<kfogel> The whole thing is silly. None of these obstructions
* sars is now known as sarnold
<malcolmr> Just to divert the conversation ever-so-slightly, could
<malcolmr> I'm sure there's a reason, but it's really annoying.
<rooneg> what is the advantage that docbook is giving us? does
<davidjames> Maybe we should leave a fork of the design document in
<wsanchez> perhaps if you use XHTML, you can have both. :)
<malcolmr> rooneg: Agreed. Good for svnbook, no real advantage for
<davidjames> It'll be like the SWS (Subversion with space) project
<maxb> I don't especially care about PDF.
<kfogel> malcomr: anchors
<kfogel> malcomr: "#foo" URLs
<kfogel> oh, *title* tags?
<malcolmr> For example, go to
<kfogel> malcomr: the two goals are: "#foo" URLs should work, and
<maxb> Given that the design document is going to grow, I think
<malcolmr> kfogel: title isn't supposed to be misused like that.
<malcolmr> Also, it's annoying.
<malcolmr> Alright, it's annoying me.
<davidjames> I think the 'title' tag enables the windowlet (which pops
<kfogel> malcomr: patches welcome, I just did what worked. I care
<maxb> I also find that scrolling up and down in a huge document
<kfogel> maxb: imho, the FAQ proves that maintaining ToC is
<malcolmr> Well if your goal is to have an annoying tooltip pop up,
<kfogel> malcomr: s/annoying// sure
<kfogel> It's not annoying to those of us who depend on it to give
<maxb> The FAQ proves very well that maintaining a ToC is
<kfogel> Do you really think the current non-maintainedness of the
<maxb> Yes, I do.
<kfogel> oops, gotta go for a bit, someone's here, back later
<maxb> Actually, not unrelated: I credit the current
<davidjames> maxb: Isn't this a bikeshed?
<davidjames> I.e., XML vs HTML, it's probably not a big difference
<malcolmr> There are some differences: tool support, semantics
* madan_ (email@example.com) has joined #svn-dev
<davidjames> Sure, but, in actual practice, for a doc that is this
<maxb> I don't view it as a bikeshed, because it's not a choice
<maxb> Problem is, we can't seem to agree on which side the
<maxb> I would also suggest that 140KB and growing is not small
<davidjames> maxb: Well, I think it's pretty much a wash, there are
<davidjames> maxb: The major advantage for HTML is that I (and kfogel
<maxb> Yes, there are. I happen to believe that XML has more.
* madan has quit (Read error: 110 (Connection timed out))
* madan_ watches as maxb polices the dev channel and the dev list
<maxb> davidjames, madan_ : What is your principle objection to
<davidjames> maxb: Both
<madan_> more than that
<madan_> difficult to change and review
<maxb> difficult to change? How? Just use a text editor, like
<madan_> <br> and <p> are more understandable than <bookinfo> and
<madan_> and on ttop of that somebody who wants to read that
<madan_> shouldnt be inconvinienced...
<madan_> better if the html is readily available
<maxb> Anyway: In conclusion, I'd prefer that the XML->HTML idea
* madan_ seconds maxb on that
<madan_> but I dont think many ppl are offline atm
<kfogel> maxb: okay, I will air on the list first, instead of
<maxb> There are many who are never on IRC
* Kamesh (firstname.lastname@example.org) has joined #svn-dev
<maxb> One additional request:
<maxb> If it goes HTML, can it please go to a set of html pages,
<maxb> Huh? How is *that* objectionable?
<madan_> it wont be searchable
<madan_> after all its not that big
<maxb> And this is why we should use docbook, so we can make
<maxb> Since there are ardent supporters of both forms
<madan_> but it doesnt really matter for a file this size
<madan_> cmon, madan_
<madan_> oops, I meant maxb
<maxb> It's 140KB already, and likely to grow
<maxb> If searching is an issue, fix up a google-form for it :-)
* madan_ wonders if it is possible to have one html with multiple html
<kfogel> madan_: with server-side includes, yes
<davidjames> No really, we already have a monolithic HTML file for
<maxb> I contest that it works fine, and desire to split it.
<kfogel> maxb: I much prefer one file (and wonder how you use your
<madan_> kfogel, so we need a webserver in the codebase?
This is an archived mail posted to the Subversion Dev mailing list.