On Sat, 25 Jan 2003, Jeff Garland wrote: > Ok, I go xsltproc going -- I ended up upgrading cygwin and I have successfully > produced a set of html docs using the instructions on the Wiki. So I'm over > the initial hump and can get on with some real work!
Great! > Now for a few questions. > > 1) I was going to try running the pdf, but the Makefile includes a Makefile.def > which is not in CVS -- any chance you can check this in? I would run the > pdf by hand, but it looks like this depends on some java and shell scripts? You can generate Makefile.def by running: ./configure <docbook-xsl-directory> To get PDF generation working, you'll need FOP (http://xml.apache.org/fop/index.html). It's a Java program that takes XSL Formatting Objects (the "fo" output) and produces PDF. The FOP distribution contains "fop.sh", which helps with locating Java and performing the actual FO->PDF conversion. The PDF generation command in the Makefile is very poor, and is essentially hardcoded to work on the machine doing the nightly documentation builds (always available at http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html). PDF generation will be a bumpy road for a little longer, because I think documentation is more important. At this point, it might be worth just verifying the output with HTML, checking it into the sandbox, and watching what the PDF looks like on the web site :) > 2) Your section on 'From HTML to BoostBook' (along with the rest of the > how to) docs are looking pretty good. One thing I would add to the table > is how to map tables. I'm assuming from looking at other sections we > are using docbook elements like <informaltable><tgroup cols="2" align="left">, > etc. Tables probably deserve their own section. I've added a stub section so I can't forget to do this... > 3) I'm assuming from the way we are processing this stuff we can > actually use any docbook element we want? Assuming that this is > the case, it would be nice to say this in the 'Documenting Libraries' > section and provide a pointer to the online reference book: > http://docbook.org/tdg/en/index.html Done. > 4) It appears that you use the <code> element within paragraphs > to format text as opposed to <programlisting>. Not clear on the > difference... Like <pre> in HTML, <programlisting> contains a block of preformatted text (presumably for a program of some sort). <code>, on the other hand, just changes the font to a monospaced font but does not consider its text to be preformatted (e.g., line breaks in <code> are not significant; line breaks in <programlisting> are significant). To be picky, <code> in HTML is actually spelled <computeroutput> in DocBook, but BoostBook supports <code> also because <computeroutput> is _waaaay_ too much to type. > 5) I'm a little unsure about how the example extraction stuff works, > but I'm sure you will explain the magic once you get around to > documenting that part :-) Short version: anything in a <source> element is written to the file named by the testcase. <snippet> pulls in code from a <programlisting> with the same name attribute. > 6) One worry is that I'm sure some users will be a bit overwhelmed > when writing reference docs with all the various tags. > I'm wondering if there will be a minimum subset that is less > feature rich with links, but still works fine that can be more > easily transitioned to? There might be. Actually, it may make sense to move the discussion of linking much later, after the discussion of documenting C++ constructs. That would limit the amount of nitpicky details in the initial sections, and it would be easier to understand the behavior of, e.g., <functionname> or <methodname> once we have the C++ constructs around. > Anyway, nice job on this -- it's looking good :-) > > Jeff Thanks for the comments. Doug ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ Boost-docs mailing list [EMAIL PROTECTED] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
