www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Ddoc config.ddoc and style sheets?

reply "Walter Bright" <newshound digitalmars.com> writes:
The new version of Ddoc should be flexible enough that people can write
config.ddoc files to cause it to generate XHTML, style sheet based HTML, or
XML output.

I'd love to see what people can come up with, so it can be incorporated as
part of the D distribution.

There's also room for wild/creative files to do things like render D
documentation in Star Trek fonts, etc!

www.digitalmars.com/d/ddoc.html
Sep 24 2005
next sibling parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Walter Bright" <newshound digitalmars.com> wrote in message 
news:dh4s2m$vhb$2 digitaldaemon.com...
 The new version of Ddoc should be flexible enough that people can write
 config.ddoc files to cause it to generate XHTML, style sheet based HTML, 
 or
 XML output.

 I'd love to see what people can come up with, so it can be incorporated as
 part of the D distribution.

 There's also room for wild/creative files to do things like render D
 documentation in Star Trek fonts, etc!

 www.digitalmars.com/d/ddoc.html

Awesome, totally awesome. This will make documentation so much easier for my project, especially since now it can be set up to ouput custom-formatted docs. However, there seems to be one major problem. Specifying a ddoc file on the commandline or setting it as the DDOCFILE in sc.ini crashes DMD. I'm not entirely sure if there's some special format I'm supposed to use, though, as I just copied the contents of the "Predefined Macros" section of the DDoc docs into a file. Are there certain macros I shouldn't be overloading, or is there some special format I should use for the ddoc files?
Sep 24 2005
parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Jarrett Billingsley" <kb3ctd2 yahoo.com> wrote in message 
news:dh54r1$16mp$1 digitaldaemon.com...

Figured I might as well post the file, in case you want to test. 
Sep 24 2005
next sibling parent "Unknown W. Brackets" <unknown simplemachines.org> writes:
You need a newline at the end of the file, at least as far as I can tell.

-[Unknown]


 "Jarrett Billingsley" <kb3ctd2 yahoo.com> wrote in message 
 news:dh54r1$16mp$1 digitaldaemon.com...
 
 Figured I might as well post the file, in case you want to test. 
 
 

Sep 24 2005
prev sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
I think the problem is the file must end in a \n.
Sep 24 2005
parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Walter Bright" <newshound digitalmars.com> wrote in message 
news:dh5b30$1bvr$1 digitaldaemon.com...
 I think the problem is the file must end in a \n.

That's it. Though you might want to fix that ;) Found a new bug though. If you try to put an embedded code section in a Params section with at least one parameter before it, such as Params: args = The list of arguments passed to the program on the command line or by the OS. The first argument is always the name of the program. ----------- void ----------- The compiler crashes with an assertion error at line 1306 of doc.c. There is no crash if the code block is in any other kind of section or if it comes before the parameters. Lastly, what is the DDOC_KEYWORD style for? It doesn't seem to be applied to any keywords, even in embedded code blocks. Is it just there for future expansion?
Sep 25 2005
parent reply "Walter Bright" <newshound digitalmars.com> writes:
"Jarrett Billingsley" <kb3ctd2 yahoo.com> wrote in message
news:dh6ij4$2d0b$1 digitaldaemon.com...
 Lastly, what is the DDOC_KEYWORD style for?  It doesn't seem to be applied
 to any keywords, even in embedded code blocks.  Is it just there for

 expansion?

Right now, it only applies to null, true and false.
Sep 25 2005
parent "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Walter Bright" <newshound digitalmars.com> wrote in message 
news:dh6lge$2f08$1 digitaldaemon.com...
 Right now, it only applies to null, true and false.

Ah, I see.
Sep 25 2005
prev sibling next sibling parent "Unknown W. Brackets" <unknown simplemachines.org> writes:
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Thanks for implementing these changes.  Now, the documentation output is 
considerably more flexible.

First, I have a few minor comments I found while making an XHTML 
config.ddoc:

If there's no newline at the end of config.ddoc, garbage is output at 
the end of the file.
There are no spaces after the commas in parameter lists, which looks 
strange (and there's a space before the comma too.)  Perhaps this is my 
fault?
It'd be very nice if there were a way to run the output automatically 
through another program (I'm thinking tidy, which cleans up/formats 
HTML) but I suppose that'd be cruft.

Attached is a config.ddoc file which should (afaict) always generate 
valid XHTML 1.0 Transitional (and 1.0 Strict, and 1.1, for that matter.) 
  It should also look fine in all commonly used browsers (Netscape 6+, 
IE 4+, Opera 6+, Safari, etc.)

-[Unknown]


 The new version of Ddoc should be flexible enough that people can write
 config.ddoc files to cause it to generate XHTML, style sheet based HTML, or
 XML output.

Sep 24 2005
prev sibling next sibling parent reply Markus Dangl <danglm in.tum.de> writes:
Walter Bright wrote:
 The new version of Ddoc should be flexible enough that people can write
 config.ddoc files to cause it to generate XHTML, style sheet based HTML, or
 XML output.
 
 I'd love to see what people can come up with, so it can be incorporated as
 part of the D distribution.
 
 There's also room for wild/creative files to do things like render D
 documentation in Star Trek fonts, etc!
 
 www.digitalmars.com/d/ddoc.html

If there is someone interested in making PDF documentation, i could use my XML/XSLT experience from the ddocwiki (http://www.quit-clan.de/docwiki/) to create XML output plus some stylesheet for XML-FO. Generating XML would be useful anyways, we could even compile CHMs from it... I'm asking because it wouldn't be worth the effort if nobody will use it...
Sep 25 2005
next sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
"Markus Dangl" <danglm in.tum.de> wrote in message
news:dh6th2$2kvo$1 digitaldaemon.com...
 If there is someone interested in making PDF documentation, i could use
 my XML/XSLT experience from the ddocwiki
 (http://www.quit-clan.de/docwiki/) to create XML output plus some
 stylesheet for XML-FO. Generating XML would be useful anyways, we could
 even compile CHMs from it...

 I'm asking because it wouldn't be worth the effort if nobody will use

I think it's worth doing. I want to include files in the D distribution so people can create XHTML, XML, CHM, RTF, PDF, Latex, Postscript, etc. with Ddoc. I generally subscribe to "build it, and they will come!" Also, I want to know if there are any technical obstacles preventing this from working, so Ddoc can be fixed. The only way to find that out is to try it.
Sep 25 2005
parent reply Markus Dangl <danglm in.tum.de> writes:
Walter Bright wrote:
 I think it's worth doing. I want to include files in the D distribution so
 people can create XHTML, XML, CHM, RTF, PDF, Latex, Postscript, etc. with
 Ddoc. I generally subscribe to "build it, and they will come!"
 
 Also, I want to know if there are any technical obstacles preventing this
 from working, so Ddoc can be fixed. The only way to find that out is to try
 it.

Okay, i'm in. My first try was to create ddoc macros for outputting XML like this: DDOC_DECL = <declaration>$0</declaration> DDOC_DECL_DD = <decldescription>$0</decldescription> DDOC_SECTIONS = <sections>$0</sections> DDOC_SUMMARY = <summary>$0</summary> and so on... There are some minor problems: For XSLT it is much easier to transform XML tags than to match on strings. Perhaps someone would want to alter the arrangement of the sections, so he has to match on the section name. Doing it like this: DDOC_SECTION_H = <sectionname>$0</sectionname> DDOC_SECTION = <section>$0</section> gives me: <sectionname>Authors:</sectionname> <section>Markus Dangl, danglm in.tum.de</section> But i would like to have seperate tags for different sections, the best way to do it would be: <sections> <authors>Markus Dangl, danglm in.tum.de</section> <license>Public Domain</license> <customsection title="Somethingelse">This is for user-defined sections</customsection > </sections> But i can't do something like pattern-matching with the DDOC Macros... IMHO it would be even better to change the behavior of DDOC to output XML by default and integrate an XSLT transformer instead of the Text Macro Processor. You can go from XML to XHTML pretty easy... But i know this would be a very fundamental change and i really appreciate the work you have done so far with ddoc.
Sep 25 2005
parent Markus Dangl <danglm in.tum.de> writes:
Looking through src/dmd/doc.c i found that it sometimes uses HTML-Like 
macros, for example:

in void Dsymbol::emitDitto(Scope *sc)
#270: b.writestring("$(BR)");
in void DocComment::writeSections(Scope *sc, Dsymbol *s, OutBuffer *buf)
#810: 	buf->writestring("$(BR)$(BR)\n");
and "$(P ...)" in highlightText.

It may be better to change these macros give them more semantic meaning, 
so they will still be useful even if we're not using HTML. (e.g. XML-Fo)
Sep 25 2005
prev sibling parent Georg Wrede <georg.wrede nospam.org> writes:
Markus Dangl wrote:
 i could use 
 my XML/XSLT experience from the ddocwiki 
 (http://www.quit-clan.de/docwiki/) to create XML output plus some 
 stylesheet for XML-FO. Generating XML would be useful anyways, 

Definitely!! If there ever was a transformation that we really need, it's XML! From that, anything can be created. That opens up the avenues for Language Independent Code Analysis, IDEs of the Future, automatic code integration from disparate languages, -- do I have to go on? Plus many, today existing uses.
Sep 25 2005
prev sibling parent reply =?ISO-8859-1?Q?Jari-Matti_M=E4kel=E4?= <jmjmak invalid_utu.fi> writes:
Walter Bright wrote:
 The new version of Ddoc should be flexible enough that people can write
 config.ddoc files to cause it to generate XHTML, style sheet based HTML, or
 XML output.
 
 I'd love to see what people can come up with, so it can be incorporated as
 part of the D distribution.
 
 There's also room for wild/creative files to do things like render D
 documentation in Star Trek fonts, etc!

It would be quite useful to support class hierarchy and call graphs. Doxygen uses dot to render those.
Sep 25 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Jari-Matti Mäkelä" <jmjmak invalid_utu.fi> wrote in message
news:dh709n$2ms3$1 digitaldaemon.com...
 Walter Bright wrote:
 The new version of Ddoc should be flexible enough that people can write
 config.ddoc files to cause it to generate XHTML, style sheet based HTML,


 XML output.

 I'd love to see what people can come up with, so it can be incorporated


 part of the D distribution.

 There's also room for wild/creative files to do things like render D
 documentation in Star Trek fonts, etc!

It would be quite useful to support class hierarchy and call graphs. Doxygen uses dot to render those.

I agree, but that'll have to wait. In the meantime, I've been using Ddoc to redo some of the Phobos documentation, and it really does cut the time down by a huge factor.
Sep 25 2005