Improving ddoc

[ketmar via Digitalmars-d]

On Thu, 01 Jan 2015 01:43:13 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d at puremagic.com>
wrote:

> On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote:
> > i can fix something if i can read it, and i can't read that Ddoc mess.
> > so i'm going to dlang.org to look at the dox instead of looking it
> > right in the Phobos sources. and if i see something that can/should be
> > fixed on dlang.org... ah, well, i have to drop the thing i was doing,
> > open another terminal, go to Phobos source directory, find the file
> > with the dox, then find the place to fix... screw it, i was looking at
> > documentation for doing completely different things!
> >
> > but see, if Phobos documentation is human-readable without
> > preprocessing, it's WAY EASIER for me to just open Phobos source file
> > and look there. and guess what i'll do if i'll see that something needs
> > fixing there? yep, i'll fix that, 'cause i'm already at the place that
> > needs fixing. the process is not distractive. and then i can do 'git
> > diff' and send a patch.
> 
> All you need is a mail client seeing as Walter offered you twice to 
> email him any fixes you have and he'll integrate them for you. (Not to 
> mention you refuse to use github etc.) Honestly if someone would pass 
> similarly constructed arguments by you, would you put any weight on 
> their opinion? I find your posts oddly awesome. Such cognitive 
> dissonance is the stuff of legends. -- Andrei

you seem to miss my point completely. i'm *not* doing any fixes at all.
if Phobos documentation will be human-readable, i will not go to
dlang.org ever, i will use Phobos sources instead. i.e. i will look for
documentation right in the Phobos sources, not on some website. and
surely, it's easy to fix something if the file where it must be fixed
is already open in your editor, and exatly on the place which needs
fixing. but going from website all way down to Phobos src, and then
struggling with Ddoc... no, thanks. i'm not reading that dox for fun
and enjoyment. if i'm reading dox it means that i got some problem that
i need to solve, and distracting me for too long from that problem is
destructive for my workflow. fixing something that is already before my
eyes and ready to be edited is ok. dropping my work to fix something
that is both far away and requires to grasp non-readable formatting is
no-no.

having human-readable formatting for documentation solves that problem.
it's still possible to generate standalone dox with it, but it's now
possible to read dox without generating anything, just in place where
that dox was created. and most existing dox can be magically converted
to human-readable format too.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20150101/b17143b3/attachment.sig>