digitalmars.D.announce - Ddoc config.ddoc and style sheets?
- Walter Bright (8/8) Sep 24 2005 The new version of Ddoc should be flexible enough that people can write
- Jarrett Billingsley (11/20) Sep 24 2005 Awesome, totally awesome. This will make documentation so much easier f...
-
Jarrett Billingsley
(32/32)
Sep 24 2005
"Jarrett Billingsley"
- Unknown W. Brackets (2/8) Sep 24 2005
- Walter Bright (1/1) Sep 24 2005 I think the problem is the file must end in a \n.
- Jarrett Billingsley (17/18) Sep 25 2005 That's it. Though you might want to fix that ;)
- Walter Bright (4/7) Sep 25 2005 future
- Jarrett Billingsley (3/4) Sep 25 2005 Ah, I see.
- Unknown W. Brackets (17/20) Sep 24 2005 Thanks for implementing these changes. Now, the documentation output is...
- Markus Dangl (7/18) Sep 25 2005 If there is someone interested in making PDF documentation, i could use
- Walter Bright (9/15) Sep 25 2005 it...
- Markus Dangl (32/39) Sep 25 2005 Okay, i'm in. My first try was to create ddoc macros for outputting XML
- Markus Dangl (9/9) Sep 25 2005 Looking through src/dmd/doc.c i found that it sometimes uses HTML-Like
- Georg Wrede (8/12) Sep 25 2005 ...
- =?ISO-8859-1?Q?Jari-Matti_M=E4kel=E4?= (3/12) Sep 25 2005 It would be quite useful to support class hierarchy and call graphs.
- Walter Bright (7/19) Sep 25 2005 or
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
"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.htmlAwesome, 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
"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. begin 666 default.ddoc M0B ]"3QB/B0P/"]B/ T*22 ]"3QI/B0P/"]I/ T*52 ]"3QU/B0P/"]U/ T* M"3QF;VYT(&-O;&]R/7)E9#XD,#PO9F]N=#X-"D),544 /0D\9F]N="!C;VQO M<CUB;'5E/B0P/"]F;VYT/ T*1U)%14X /0D\9F]N="!C;VQO<CUG<F5E;CXD M,#PO9F]N=#X-"EE%3$Q/5R ]/&9O;G0 8V]L;W(]>65L;&]W/B0P/"]F;VYT M/ T*0DQ!0TL /0D\9F]N="!C;VQO<CUB;&%C:SXD,#PO9F]N=#X-"E=(251% M(#T M96%D/ T*"3Q-151!(&AT=' M97%U:78](F-O;G1E;G0M='EP92( 8V]N=&5N M=#TB=&5X="]H=&UL.R!C:&%R<V5T/75T9BTX(CX-" D\=&ET;&4^)"A4251, M12D\+W1I=&QE/ T*"3PO:&5A9#X M*0T*1$1/0U]314-424].4R /2 D, T*1$1/0U]354U-05)9(" /2 D, T* M/2 D*$1,("0P*0T*1$1/0U]005)!35, (" /2 D*% )"A404),12 D,"DI M0U]04UE-0D],"3T )"A5("0P*0T*1$1/0U]+15E73U)$"3T )"A"("0P*0T* 41$1/0U]005)!30D]("0H22 D,"D` ` end
Sep 24 2005
"Unknown W. Brackets" <unknown simplemachines.org> 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
I think the problem is the file must end in a \n.
Sep 24 2005
"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
"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 forfutureexpansion?Right now, it only applies to null, true and false.
Sep 25 2005
"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
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
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.htmlIf 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
"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 useit... 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
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
Looking through src/dmd/doc.c i found that it sometimes uses HTML-Like macros, for example: in void Dsymbol::emitDitto(Scope *sc) in void DocComment::writeSections(Scope *sc, Dsymbol *s, OutBuffer *buf) 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
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
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
"Jari-Matti Mäkelä" <jmjmak invalid_utu.fi> wrote in message news:dh709n$2ms3$1 digitaldaemon.com...Walter Bright wrote:orThe 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,asXML output. I'd love to see what people can come up with, so it can be incorporatedI 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.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