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