www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - PDF version of D manuals

reply Walter Bright <newshound digitalmars.com> writes:
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
next sibling parent reply Lars Ivar Igesund <larsivar igesund.net> writes:
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
next sibling parent reply Lars Ivar Igesund <larsivar igesund.net> writes:
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
next sibling parent Brad Anderson <brad dsource.org> writes:
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.)


 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. 
 


hear hear!!

BA
Nov 29 2006
prev sibling next sibling parent reply Markus Dangl <danglm in.tum.de> writes:
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
next sibling parent Steve Horne <stephenwantshornenospam100 aol.com> writes:
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
prev sibling parent Lars Ivar Igesund <larsivar igesund.net> writes:
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
prev sibling parent reply =?ISO-8859-1?Q?Jari-Matti_M=E4kel=E4?= <jmjmak utu.fi.invalid> writes:
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.)


 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.


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
next sibling parent reply Lars Ivar Igesund <larsivar igesund.net> writes:
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.)


 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.


 
 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
parent =?UTF-8?B?SmFyaS1NYXR0aSBNw6RrZWzDpA==?= <jmjmak utu.fi.invalid> writes:
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
prev sibling parent reply Steve Horne <stephenwantshornenospam100 aol.com> writes:
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
parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
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 ?)


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
next sibling parent Carlos Santander <csantander619 gmail.com> writes:
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?



 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
prev sibling parent =?ISO-8859-1?Q?Jari-Matti_M=E4kel=E4?= <jmjmak utu.fi.invalid> writes:
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
prev sibling next sibling parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
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
prev sibling next sibling parent Micke <dronten gmail.com> writes:
 
 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
prev sibling parent Steve Horne <stephenwantshornenospam100 aol.com> writes:
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
prev sibling next sibling parent reply Johan Granberg <lijat.meREM OVE.gmail.com> writes:
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
parent BCS <BCS pathlink.com> writes:
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
prev sibling next sibling parent Mars <nospam null.void> writes:
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
prev sibling next sibling parent KlausO <oberhofer users.sourceforge.net> writes:
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
prev sibling next sibling parent Kazuhiro Inaba <kiki kmonos.net> writes:
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
prev sibling parent xs0 <xs0 xs0.com> writes:
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