digitalmars.D.bugs - [Issue 2060] New: some ddoc design typos
- d-bugmail puremagic.com (61/61) Apr 30 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
- d-bugmail puremagic.com (4/4) Apr 30 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
- d-bugmail puremagic.com (12/12) Apr 30 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
- d-bugmail puremagic.com (12/12) May 01 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
- d-bugmail puremagic.com (12/12) May 01 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
- d-bugmail puremagic.com (5/5) May 11 2008 http://d.puremagic.com/issues/show_bug.cgi?id=2060
http://d.puremagic.com/issues/show_bug.cgi?id=2060 Summary: some ddoc design typos Product: D Version: 2.012 Platform: PC URL: http://www.digitalmars.com/d/2.0/ddoc.html OS/Version: Windows Status: NEW Severity: enhancement Priority: P2 Component: DMD AssignedTo: bugzilla digitalmars.com ReportedBy: terranium yandex.ru 1. ddoc is html-oriented. Because $(BODY) macro contains comment <!-- Generated by Ddoc from file.d --> AFAIK this is the only place where source file name and generator's name are contained and this comment is atomic (hard to parse) and intranslatable. This information should be provided in macros, separated from $(BODY) and .ddoc template should give credits to the generator. One more issue here. In delineated code examples <, > and & are replaced with corresponding entity references. Well... this one just helps a lot in generating xml documentation :) I'm affraid this breaks documentation a little when generating to plain text. Although here can be workaround: one can generate plain text documentation from xml one. 2. ddoc is display-oriented. Well... not ddoc itself, it's rather its specification where "Basic Formatting Macros" are listed. This tends to be percieved as built-in macros while they are private macros for internal use in default .ddoc template, so they should not be exposed as standard. More meaningful formatting macros should be used. In terms of html Phrase Elements ( http://www.w3.org/TR/html401/struct/text.html#h-9.2.1 ) should be used instead of Font Style Elements ( http://www.w3.org/TR/html401/present/graphics.html#h-15.2 ). BTW you already did this for member lists marking them up by dl/dt/dd instead of table or ul. WCAG 1.0: http://www.w3.org/TR/WCAG10-HTML-TECHS/#text WCAG 2.0: Using semantic elements to mark up structure http://www.w3.org/TR/2007/WD-WCAG20-TECHS-20071211/G115.html "The objective of this technique is to mark up the structure of the Web content using the appropriate semantic elements. In other words, the elements are used according to their meaning, not because of the way they appear visually." Understanding Success Criterion 1.3.1 http://www.w3.org/TR/2007/WD-UNDERSTANDING-WCAG20-20071211/content-structure-separation-programmatic.html "The intent of this Success Criterion is to ensure that information and relationships that are implied by visual or auditory formatting are preserved when the presentation format changes. For example, the presentation format changes when the content is read by a screen reader or when a user style sheet is substituted for the style sheet provided by the author." 3. Formatting of custom sections. Default declaration of DDOC_SECTION_H is DDOC_SECTION_H = $(B $0)$(BR)$(BR) But $0 sould not contain trailing colon, which is provided by ddoc engine and is hard to remove, this colon sould be moved to DDOC_SECTION_H macro DDOC_SECTION_H = $(B $0:)$(BR)$(BR) so its apperance could be customizable. Ideal variant is for DDOC_SECTION macro to have 2 parameters: $0 for section title and $1 for section body, this will provide higher customizability for section formatting, for example, for xml output DDOC_SECTION = <section name="$0">$1</section> 4. It seems like ddoc forces DDOC_BLANKLINE after DDOC_SECTION_H. DDOC_BLANKLINE can't be made empty because this will change its meaning and break existing code relying on DDOC_BLANKLINE macro. --
Apr 30 2008
http://d.puremagic.com/issues/show_bug.cgi?id=2060 1. Ooh... or DDOC_COMMENT macro is used here? --
Apr 30 2008
http://d.puremagic.com/issues/show_bug.cgi?id=2060 I just posted a request for comments and proposals on the DNG. In short, the use of DDOC need to be much more semantic, and generated DDOC output should never be passed back to the doc engine as raw output. While this will increase the complexity of the typical .ddoc script, as well as require several new standard macros, the result will be richer output. This will also open the door for XML-based documentation, which is a handy way to move beyond DDOC's limitations. http://www.digitalmars.com/webnews/newsgroups.php?art_group=digitalmars.D&article_id=70806 --
Apr 30 2008
http://d.puremagic.com/issues/show_bug.cgi?id=2060 UPD: 1. DDOC_COMMENT is used. 4. I was wrong here 5. In module-level copyright section <, > and & are not replaced with entities. 6. In all sections if valid opening or closing tag is encountered, it's passed unchanged to the output. This breaks xml output, while html doesn't suffer for this behavior. This is a consequence of ddoc engine being html-oriented. Workaround: developer must be aware of the documentation output format and use <, > and & carefully. --
May 01 2008
http://d.puremagic.com/issues/show_bug.cgi?id=2060 Test cases. 5. /++ Copyright: me < & > you +/ module foo.bar; 6. ///Summary for </html> Foo ends html document class Foo{} --
May 01 2008
http://d.puremagic.com/issues/show_bug.cgi?id=2060 The <!-- ... --> comment is generated by DDOC_COMMENT, which can be overridden by the user. The other suggestions are good. --
May 11 2008