www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - ddoc-xml, first demo

reply Markus Dangl <danglm in.tum.de> writes:
XML output works :)

Finally i got some XML ouput to work. I'm including a zip file including:

xml.ddoc       - the ddoc macro definition file for XML output
ddoc.dtd       - a DTD for the resulting XML documents
ddoc2xhtml.xsl - an XSLT stylesheet for transforming DDOC-XML to XHTML
                  (automatically included from the XML files for viewing
                   them in the browser)
style.css      - A CSS stylesheet used by ddoc2xhtml.xsl
example.d      - An example d source file with lots of ddoc comments


To test it you would:
1. Tell dmd to use the xml.ddoc (i used the sc.ini version, don't know
    if you can specify this on the command line)
2. Run dmd (or build) with "-D" parameter on your source file
3. Rename the resulting .html file to .xml
4. Open in with your browser (ddoc2xhtml.xsl and style.css have to be
    in the same directory as the xml file)


Problems:
1. Code sections (example code) get messed up with lots of linebreaks.
    This seems to be the fault of the macro processor :(
2. You have to manually rename the file to .xml
3. No support for multiple input files yet, thus no inter-linking.
    Perhaps we could add something to Dereks "build" tool to join
    the resulting XML files in a special way, then run several commands
    on it (for example: to generate XHTML, CHM, PDF in one run!)


I didn't test it with lots of source yet, remember: it is just a demo.
If you want to change some colors or font-sizes etc. you may edit the 
css file.
If you want to change to whole layout of the output, i'm afraid you'll 
have to edit the xsl file, so you have to know how to use XSLT...

I'm working on XSL-FO output now, so we could create PDF documentation.

I hope this will be useful,
  - Markus Dangl
Sep 30 2005
parent reply "Walter Bright" <newshound digitalmars.com> writes:
"Markus Dangl" <danglm in.tum.de> wrote in message
news:dhjopu$1u9v$1 digitaldaemon.com...

 XML output works :)


Cool!


 Finally i got some XML ouput to work. I'm including a zip file including:

 xml.ddoc       - the ddoc macro definition file for XML output
 ddoc.dtd       - a DTD for the resulting XML documents
 ddoc2xhtml.xsl - an XSLT stylesheet for transforming DDOC-XML to XHTML
                   (automatically included from the XML files for viewing
                    them in the browser)
 style.css      - A CSS stylesheet used by ddoc2xhtml.xsl
 example.d      - An example d source file with lots of ddoc comments


Can I include it in the dmd distribution?


 To test it you would:
 1. Tell dmd to use the xml.ddoc (i used the sc.ini version, don't know
     if you can specify this on the command line)


Just list the .ddoc files on the command line, like you would a .lib file.

    dmd -D foo.d xml.ddoc


 2. Run dmd (or build) with "-D" parameter on your source file
 3. Rename the resulting .html file to .xml


Use the -Df flag to set the output file name:

    dmd -D -Dffoo.xml foo.d xml.ddoc


 4. Open in with your browser (ddoc2xhtml.xsl and style.css have to be
     in the same directory as the xml file)


 Problems:
 1. Code sections (example code) get messed up with lots of linebreaks.
     This seems to be the fault of the macro processor :(


Hmm. I thought I fixed that in the latest version.


 2. You have to manually rename the file to .xml


The -Df flag rides to the rescue here.


 3. No support for multiple input files yet, thus no inter-linking.
     Perhaps we could add something to Dereks "build" tool to join
     the resulting XML files in a special way, then run several commands
     on it (for example: to generate XHTML, CHM, PDF in one run!)


That'll probably have to wait.


 I didn't test it with lots of source yet, remember: it is just a demo.
 If you want to change some colors or font-sizes etc. you may edit the
 css file.
 If you want to change to whole layout of the output, i'm afraid you'll
 have to edit the xsl file, so you have to know how to use XSLT...

 I'm working on XSL-FO output now, so we could create PDF documentation.


I'd love to see the result in PDF!
Sep 30 2005
next sibling parent reply Derek Parnell <derek psych.ward> writes:
On Fri, 30 Sep 2005 19:13:25 -0700, Walter Bright wrote:


 "Markus Dangl" <danglm in.tum.de> wrote in message


[snip]


 1. Tell dmd to use the xml.ddoc (i used the sc.ini version, don't know
     if you can specify this on the command line)


 
 Just list the .ddoc files on the command line, like you would a .lib file.
 
     dmd -D foo.d xml.ddoc


Note: The contents of a .ddoc file must not be in the form  of D comments.
If you do that you get weird results. Just code a .ddoc file AS IF it
already was a document comment.
 


 Problems:
 1. Code sections (example code) get messed up with lots of linebreaks.
     This seems to be the fault of the macro processor :(


 
 Hmm. I thought I fixed that in the latest version.


No. This is a problem. You insert new lines where a space was originally
coded. I notice this especially with DDOC_PSYMBOL macros. 
 


-- 
Derek Parnell
Melbourne, Australia
2/10/2005 12:47:51 AM
Oct 01 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Derek Parnell" <derek psych.ward> wrote in message
news:18k7sjg47btw4.xazz4zd88o3g$.dlg 40tude.net...

 Note: The contents of a .ddoc file must not be in the form  of D comments.
 If you do that you get weird results. Just code a .ddoc file AS IF it
 already was a document comment.


That's right. Specifically, if in a .d source file you might have:

/*****
 * blah, blah, blah
 *
 * More erudite blah, blah, blah.
 * Macros:
 *    FOO = BAR
 *    MAX = the maximum of
 *        x and x's ilk
 *    ABC = def
 */

A corresponding .ddoc file would be just the contents of the Macros section:

FOO = BAR
MAX = the maximum of
        x and x's ilk
ABC = def

Nothing but macro definitions go in a .ddoc file, not even "Macros:".
Oct 01 2005
prev sibling parent Markus Dangl <danglm in.tum.de> writes:
 
 Can I include it in the dmd distribution?


That would be great! I'd say it should be public domain or GPL (or sth 
similar)...
Whichever you like better :)


3. Rename the resulting .html file to .xml


 
 Use the -Df flag to set the output file name:
 
     dmd -D -Dffoo.xml foo.d xml.ddoc


Oh, right :)
I thought it might be a good option to set only the extension, so you 
wouldn't have to specify the whole filename for every file that gets 
built. But this can be solved by scripting or by the build tool, of course.


Problems:
1. Code sections (example code) get messed up with lots of linebreaks.
    This seems to be the fault of the macro processor :(


 
 Hmm. I thought I fixed that in the latest version.


I tried it with dmd 0.134, maybe i got something wrong in the ddoc file, 
although i can't see where...


I didn't test it with lots of source yet, remember: it is just a demo.
If you want to change some colors or font-sizes etc. you may edit the
css file.
If you want to change to whole layout of the output, i'm afraid you'll
have to edit the xsl file, so you have to know how to use XSLT...

I'm working on XSL-FO output now, so we could create PDF documentation.


 
 I'd love to see the result in PDF!


Hey i just got the XSLT finished :)
I'm announcing it in a new thread.
Oct 02 2005