Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

On Tuesday, 30 December 2014 at 01:35:57 UTC, Andrei Alexandrescu 
wrote:
> On 12/29/14 12:04 PM, Jacob Carlborg wrote:
>> On 2014-12-29 20:48, Walter Bright wrote:
>>
>>> I don't care much for hybrids, they are confusing and ugly.
>>
>> Markdown already support raw HTML. We could use Markdown but 
>> with Ddoc
>> macros instead of raw HTML.
>>
>> BTW, Ddoc macros are really ugly.
>
> Ideas for a better syntax? I like the idea of a uniform syntax 
> for all macros instead of learning one syntax for each artfact. 
> -- Andrei

Current syntax:

$(B bolded)
OO O      O

* 4 characters of overhead
* The characters are 'big' and seem like text (especially $),
   taking attention away from the actual content. Different
   from e.g. **bold** or `italic`
* To type, needs 6 keypresses
   - 2 shifts + 4 keys (shift held for one key)
   - as a person with RSI, this is relevant to me
* Need parens even for 1-argument version, increasing
   lisp-ness with nested macros

-----------------------------
Idea: short 1-argument syntax
-----------------------------


I think one way to improve this would be to add an equivalent of 
the
short template instantiation syntax:

   someFunction(to!(ReturnType!T))

is less lispy and more readable than

   someFunction(to!(ReturnType!(T)))

(especially with longer lines, more args, deeper nestings)



similarly e.g. (not proposing this exact syntax - just an example)

   $(LI B$bold D$true)

is more readable than

   $(LI $(B bold) $(D true))

And requires only 2 keypresses (including shift) for the 
1-parameter macros.

Of course, this only helps with 1-parameter macros, but that's 
very often the worst source of visual noise in DDoc, especially 
with things like list items and tables (nesting), especially if 
the lines are long.


--------------------------------------
Idea: 2(3 with space) character syntax
--------------------------------------

I'm not sure if this is viable without causing more damage than
benefit (too much escaping).

Idea: use 2 delimiting characters, preferably 'small' characters 
that don't distract.

E.g (again, these are not actual proposals, just to illustrate 
the point):

   `B bold`

(very little visual noise but perhaps a bit too little/easy to 
miss, 3 keypresses including space)

   ;B bold;

(slightly more visual noise but not too distracting, but
  ';' is probably too common character so there could be
  too much escaping, 3 keypresses)


.. etc.