On Mon, 29 Dec 2014 20:30:48 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 12/29/14 6:49 PM, ketmar via Digitalmars-d wrote: > > On Mon, 29 Dec 2014 18:43:56 -0800 > > Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote: > > > >> On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote: > >>> it's great that Ddoc is good for making books. but it's not so great > >>> that it's bad for documenting source code. > >> > >> I also use it for all the documentation on the Digital Mars site, which > >> include > >> a lot of coding examples, the articles I wrote for Dr. Dobb's about code, > >> all > >> the documentation on walterbright.com, etc. > > > > yes, that's exactly why it's not so great for documenting source code. > > you basically invented your own TeX, which has alot of features to > > write stand-alone texts, but almost completely unreadable as a source > > code documentation without preprocessor. Ddoc is just too powerful. > > I use (La)TeX macros all the time, and although necessary they're beyond > awful. DDoc macros are a lot nicer and more consistent by comparison. > They are not, however, as powerful. -- Andrei i don't want to say that Ddoc is better or worse than (La)TeX. the problem is that it unreadable due to visual noise. my point is that Ddoc documentation should be easily readable without preprocessing, right in the source code. markdown, textile, restructured... see the pattern? they all easily readable by humans without preprocessing. Ddoc is not. it is painful to read "rich" Ddoc comments AND it is painful to write 'em. that's why Ddoc is "too powerful": it has great macro system which gives Ddoc great power, but for the price. this price is "visual noise". most people don't need DTP package in documentation, they need simple, clean and human-readable syntax for WRITING that documentation in the first place. Ddos is perfectly usable, but it's uncomfortable to write nice documentation with it. Ddoc is for writing *reference* *documentation*, not complete documentation books. and it is simply too powerful for that. having Ddoc is great, but it's oftenly overkill to use it. i believe that Ddoc should be opt-in, and by default D should use one of the human-readable text formatting languages with some D-specific extensions (like easy cross-referencing, for example). most people will be OK with simple language for documenting API and will resort to "real Ddoc" only when they want to write something like wordy and detailed explanation of internal algorithms and such.
signature.asc
Description: PGP signature