digitalmars.D.announce - PDF version of D manuals
- Walter Bright <newshound digitalmars.com> Nov 29 2006
- Lars Ivar Igesund <larsivar igesund.net> Nov 29 2006
- Lars Ivar Igesund <larsivar igesund.net> Nov 29 2006
- Brad Anderson <brad dsource.org> Nov 29 2006
- Markus Dangl <danglm in.tum.de> Nov 29 2006
- Steve Horne <stephenwantshornenospam100 aol.com> Nov 30 2006
- Lars Ivar Igesund <larsivar igesund.net> Nov 30 2006
- =?ISO-8859-1?Q?Jari-Matti_M=E4kel=E4?= <jmjmak utu.fi.invalid> Nov 30 2006
- Lars Ivar Igesund <larsivar igesund.net> Nov 30 2006
- Steve Horne <stephenwantshornenospam100 aol.com> Nov 30 2006
- =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> Nov 29 2006
- Micke <dronten gmail.com> Nov 29 2006
- Steve Horne <stephenwantshornenospam100 aol.com> Nov 30 2006
- Johan Granberg <lijat.meREM OVE.gmail.com> Nov 29 2006
- BCS <BCS pathlink.com> Nov 29 2006
- Mars <nospam null.void> Nov 29 2006
- KlausO <oberhofer users.sourceforge.net> Nov 29 2006
- Kazuhiro Inaba <kiki kmonos.net> Nov 29 2006
- xs0 <xs0 xs0.com> Nov 30 2006
I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
Nov 29 2006
Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
htmldoc should be able to do what you want. If started without any arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download. -- Lars Ivar Igesund blog at http://larsivi.net DSource & #D: larsivi
Nov 29 2006
Lars Ivar Igesund wrote:Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
htmldoc should be able to do what you want. If started without any arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources. If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working. -- Lars Ivar Igesund blog at http://larsivi.net DSource & #D: larsivi
Nov 29 2006
Brad Anderson <brad dsource.org> Lars Ivar Igesund wrote:Lars Ivar Igesund wrote:Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources. If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working.
hear hear!! BA
Nov 29 2006
Lars Ivar Igesund schrieb:A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources. If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working.
This is almost what i intended to do by making DDoc spit out (custom) XML for me. But since DDoc allows for HTML Tags to be included in the documentation i couldn't get it working without additional tools, and thats the point where i left...
Nov 29 2006
On Thu, 30 Nov 2006 01:27:04 +0100, Markus Dangl <danglm in.tum.de> wrote:Lars Ivar Igesund schrieb:A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources. If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working.
This is almost what i intended to do by making DDoc spit out (custom) XML for me. But since DDoc allows for HTML Tags to be included in the documentation i couldn't get it working without additional tools, and thats the point where i left...
Here's an admittedly long term thought... 1. Find out which HTML tags actually get used in DDoc. 2. Set up DDoc so it recognises those tags, and rejects any it doesn't know. 3. Extend DDoc so it can generate other formats. -- Remove 'wants' and 'nospam' from e-mail.
Nov 30 2006
Markus Dangl wrote:Lars Ivar Igesund schrieb:A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources. If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working.
This is almost what i intended to do by making DDoc spit out (custom) XML for me. But since DDoc allows for HTML Tags to be included in the documentation i couldn't get it working without additional tools, and thats the point where i left...
That is a problem, possibly one could use XML namespaces to separate the DocBook from the rest. Still, if one wants to use the XML to generate PDF, then having HTML in there is not a good thing. Should be possible to transform the HTML to DocBook though. -- Lars Ivar Igesund blog at http://larsivi.net DSource & #D: larsivi
Nov 30 2006
Lars Ivar Igesund wrote:Lars Ivar Igesund wrote:Walter Bright wrote:(The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources.
I've used DDoc + some xml generation rules found in this ng a year or two ago for small projects. Then converted the xml to pdf using FOP. I think the weakest link is the DDoc implementation. It does not always generate valid and/or well-formed xml so I have made ad hoc filtering rules for the "xml"-like output. Also the FOP generates separate pdf files for every source file. I've just put them together with pdftk.If someone would like to go this route, I might be able to give further tips, I'm setting up a similar process where I'm currently working.
I would prefer adding a proper support for D syntax and semantics to doxygen. There's not much point in reinventing the wheel again.
Nov 30 2006
Jari-Matti Mäkelä wrote:Lars Ivar Igesund wrote:Lars Ivar Igesund wrote:Walter Bright wrote:(The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
A solution that would be more troublesome to implement at first, but that would be more powerful later (and for the D community at large), is to make it possible for DDoc to output DocBook XML (see http://www.docbook.org ), which through some careful transformations can be transformed to any format you like (for X/HTML, just XSL transformations are necessary, using XSL transformations + a XSL-FO processor like FOP (http://xmlgraphics.apache.org/fop), almost any format can be produced, including PDF), and all from the same XML sources.
I've used DDoc + some xml generation rules found in this ng a year or two ago for small projects. Then converted the xml to pdf using FOP. I think the weakest link is the DDoc implementation. It does not always generate valid and/or well-formed xml so I have made ad hoc filtering rules for the "xml"-like output. Also the FOP generates separate pdf files for every source file. I've just put them together with pdftk.
Since the DocBook documents can import others, and you can pass only the main one to FOP, it should be possible to create partial DocBook documents, for instance chapters, and import those in the main document. For larger documents, it almost always is smart to divide into several XML files in any case. -- Lars Ivar Igesund blog at http://larsivi.net DSource & #D: larsivi
Nov 30 2006
Lars Ivar Igesund wrote:Since the DocBook documents can import others, and you can pass only the main one to FOP, it should be possible to create partial DocBook documents, for instance chapters, and import those in the main document. For larger documents, it almost always is smart to divide into several XML files in any case.
Sure. I've just used DDoc for very small projects. I find myself much more productive using doxygen because of the integrated class hierarchy / call graphs. It's just that it needs some preprocessing to be able to handle some of the "newest" features like templates and inner classes.
Nov 30 2006
On Thu, 30 Nov 2006 11:42:27 +0200, Jari-Matti Mäkelä <jmjmak utu.fi.invalid> wrote:I would prefer adding a proper support for D syntax and semantics to doxygen. There's not much point in reinventing the wheel again.
Yes, but then adding D support to Doxygen is re-inventing the wheel in the sense that Doxygen then has to parse and understand D. Also, I quite like the idea that documentation, unit tests, and target code all reflect the exact same understanding of the original source code. If you use Doxygen and VC++, you'll find some odd things occasionally happen in documentation because Doxygen doesn't understand some Microsoft-specific code (__if_exists for instance). What might be nice is a standardised intermediate format that compilers could generate, and documentation tools could then process. -- Remove 'wants' and 'nospam' from e-mail.
Nov 30 2006
Steve Horne wrote:I would prefer adding a proper support for D syntax and semantics to doxygen. There's not much point in reinventing the wheel again.
Yes, but then adding D support to Doxygen is re-inventing the wheel in the sense that Doxygen then has to parse and understand D.
Doxygen currently understands a simple subset of "D 1.0", even if doesn't understand much of templates and "D 2.0". (Currently using it instead of Ddoc, which just outputs blank for all code that doesn't have any comments added ?) We've been using this to share docs between D/C#/Java, that also have one "native" documentation format each. I'm sure the D support in Doxygen could be improved... http://www.prowiki.org/wiki4d/wiki.cgi?DoxygenIssues But for the D "manual" (specification), there are probably better formats to use than those done for commenting code ? --anders
Nov 30 2006
Anders F Björklund escribió:Steve Horne wrote:I would prefer adding a proper support for D syntax and semantics to doxygen. There's not much point in reinventing the wheel again.
Yes, but then adding D support to Doxygen is re-inventing the wheel in the sense that Doxygen then has to parse and understand D.
Doxygen currently understands a simple subset of "D 1.0", even if doesn't understand much of templates and "D 2.0". (Currently using it instead of Ddoc, which just outputs blank for all code that doesn't have any comments added ?)
You know, that I'd like. Maybe a switch (-Ddocall) to tell ddoc to output everything?We've been using this to share docs between D/C#/Java, that also have one "native" documentation format each. I'm sure the D support in Doxygen could be improved... http://www.prowiki.org/wiki4d/wiki.cgi?DoxygenIssues But for the D "manual" (specification), there are probably better formats to use than those done for commenting code ? --anders
-- Carlos Santander Bernal
Nov 30 2006
Anders F Björklund wrote:Steve Horne wrote:I would prefer adding a proper support for D syntax and semantics to doxygen. There's not much point in reinventing the wheel again.
Yes, but then adding D support to Doxygen is re-inventing the wheel in the sense that Doxygen then has to parse and understand D.
Yes, but AFAIK Doxygen is much bigger project than DDoc. So there's a lot more to reinvent in DDoc. I can see the benefits that DDoc has, but from the outside it looks like it has been made for one purpose - to produce very simple html code. There are no bells and whistles to produce customized large scale documentation. And it's not that straightforward to create flexible macros for other output formats. But that's a good basis for creating something better, of course. :)Doxygen currently understands a simple subset of "D 1.0", even if doesn't understand much of templates and "D 2.0". (Currently using it instead of Ddoc, which just outputs blank for all code that doesn't have any comments added ?) But for the D "manual" (specification), there are probably better formats to use than those done for commenting code ?
Of course. But for the standard libraries they are quite handy.
Nov 30 2006
Lars Ivar Igesund wrote:htmldoc should be able to do what you want. If started without any arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
Much earlier I posted a script to generate a PDF version of the HTML using HTML Tidy and HtmlDoc, not sure if it still works but you might want to have a look at: http://www.algonet.se/~afb/d/SPECIFICATION.zip It did look a little like a web page that had been printed to PDF... :-) --anders
Nov 29 2006
htmldoc should be able to do what you want. If started without any arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
Windows version 1.8.24 http://users.tpg.com.au/naffall/htmldoc.html
Nov 29 2006
On Wed, 29 Nov 2006 21:14:12 +0100, Lars Ivar Igesund <larsivar igesund.net> wrote:htmldoc should be able to do what you want. If started without any arguments, it pops up a gui, but it should be no problem to script it. http://www.htmldoc.org It should be easily available for your Linux distribution, seems to be more troublesome to find a free Windows download.
I have an older Windows version - v1.8.23, with source - if needed, from when it was still easy to get the free version. AFAIK it is legal to share it. I always used the GUI to set things up, but then used the command line to do updates. It mostly worked well, so long as you are aware of it's little quirks (e.g. it used to fail if it couldn't find a H1). The only thing is that between MikTeX, OpenOffice 2, and the fact that I shelled out for Adobe Creative Suite last year, I don't have any real use for it any more and stopped looking for updates quite a while ago. -- Remove 'wants' and 'nospam' from e-mail.
Nov 30 2006
Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
You could probably make Ddoc output to latex and then compile that into pdf.
Nov 29 2006
Johan Granberg wrote:Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
You could probably make Ddoc output to latex and then compile that into pdf.
Dosn't DDoc have the processing macros in another file? IIRC it should be easy to have it dump both HTML and LaTeX and dump the latex into a PDF. p.s. If you don't alredy have it, this is a farly painless LaTeX for win package: http://www.miktex.org/
Nov 29 2006
If you are interested in a more elaborate solution than a simple html2pdf script take a look at the system developed for the FreeBSD project. Documentation (books, articles, the website, etc.) is written in DocBook format (SGML) and html, text, pdf, etc, versions are generated from it. It works really well. http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html http://www.freebsd.org/docproj/
Nov 29 2006
Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
I have made very good experiences with tbook. - Tags are similar to LaTeX commands. If you know LaTeX you get into it faster. - It's not not so burden as docbook (tbook 80 tags - docbook ~400 tags). - The PDF output via LaTeX is IMHO excellent and could be customized. - Many output formats. I use it to create PDF and HTMLHelp (via docbook) from one source. - It is available for Windows and Linux. See http://tbookdtd.sourceforge.net/ for more details. Klaus
Nov 29 2006
At 29 Nov 2006 11:46:23 -0800 Walter Bright wrote:(The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
Btw, why don't you put the Ddoc files into the public? For some purposes like automatic manipulation or conversion of the manual, Ddoc version will be more handy than the html version. (At least for me, doing Japanese translation of the manual, it'll be much more helpful! :) ) -- Kazuhiro Inaba
Nov 29 2006
Walter Bright wrote:I've been taking some heat lately about the D web site not making available a PDF version of the D manual that can be downloaded, printed, and read offline. I know some people have made PDFs of the manual before. The trouble is, they rapidly go out of date. So I'm interested in if anyone can recommend a tool that can take text and convert it to PDFs. I'm not interested in a tool with a gui interface, I want one that can be driven from a script, so this can be done automatically with each new release. (The html version of the manual is currently created automatically using a script from Ddoc text files. Such has really cut the workload of maintaining a common look/feel of the site.)
I've had relatively good results by using css2xslfo and Apache FOP. css2xslfo has some support for XHTML (and, obviously CSS), so that may be the easiest way to go, considering the current output is HTML already. http://www.re.be/css2xslfo/ http://xmlgraphics.apache.org/fop/ xs0
Nov 30 2006