On 03/11/2012 07:01 PM, Stewart Gordon wrote:
> On 11/03/2012 20:59, Ary Manzana wrote:
>> On 03/11/2012 05:33 PM, Stewart Gordon wrote:
> <snip>
>>> Because that's what Javadoc relies on as a means for a program
>>> distributed in binary form to call custom code.
>>
>> What do you mean by "custom code"?
>
> Code written and compiled by a user of the tool, of course. Or maybe
> written by a third party unconnected with the tool's creator.
>
> <snip>
>> Replace it. Macros to document code? I think that's a bit too much...
>
> The advantage of a macro system is that it's easily extensible by the
> user. Does your proposed system provide this?

No, but I never needed it. Nor I know anyone that needed it (in Java, C#, Ruby, Pyhton and PHP).

Give me an example of a macro you'd use in your documentation, that's not: bold, italic, underlined, lists, tables, links, named sections, code blocks and images.

>
> <snip>
>> And you can always make a tool to convert ddoc to the new format (I
>> believe with ddoc
>> macros?)
> <snip>
>
> You mean make a tool that leaves D code unchanged, but uses the ddoc
> macro system to convert documentation comments to the new format?

Yes.

>
> Stewart.

On 11/03/2012 22:30, Ary Manzana wrote:
<snip>
> Give me an example of a macro you'd use in your documentation, that's not: bold, italic,
> underlined, lists, tables, links, named sections, code blocks and images.
<snip>

Emphasis possibly.  Inline code snippets.  Possibly sample input/output.

But even if you do come up with a list of things that have a genuine use case that you think is exhaustive, someone'll sooner or later come up with another one that isn't on your list.

Moreover, macros aren't just to provide access to the features of the target documentation format.  They're also used to enable specific uses of these features to be written in the source more nicely.  For example, I've just found myself setting one up for links to issues on Bugzilla.

Stewart.

On 3/10/2012 5:08 PM, Stewart Gordon wrote:
> The default macros built into DDoc leave something to be desired in terms of
> HTML structure, for example:
>
> - presentational <font>, <big> and <small> tags, rather than CSS equivalents
> - presentational details coded directly into the macros called by DDoc, rather
> than delegated to CSS classes
> - <br><br> to separate paragraphs, rather than <p></p> to enclose them.

The idea behind this is simple - a naive use of it should generate content that is renderable. Requiring the user to provide a css file thwarts that goal.

On Monday, 12 March 2012 at 02:03:03 UTC, Walter Bright wrote:
> The idea behind this is simple - a naive use of it should generate content that is renderable. Requiring the user to provide a css file thwarts that goal.

Simple solution: include some embedded css in the default
DDOC macro as <style> tags.

Then you have something that just works out of the box,
and continues to work as you tweak it into something
better.

On Sun, 11 Mar 2012 01:08:20 +0000
Stewart Gordon <smjg_1998@yahoo.com> wrote:

> Has anybody else got further with getting logical HTML out of DDoc? Have you been using DDoc to generate some internal format and then some other program to turn it into HTML, or what?

Excuse me for jumping into the thread, but I hope it's relevant...

I wonder whether you can recommend using Ddoc for writing general-purpose documentation like user's manual for e.g. application written in D which has to be split into logical parts (chapters, sections,...) as well as use hyperlinking, addding pictures, tables etc.?

Or do you believe it's better to use more specialized tool like reST markup with Sphinx, AsciiDoc, LaTeX/LyX...?

Let me add that we'd like to have nice HTML output which can be invoked within application itself as well as quaility output in the form of PDF file.


Sincerely,
Gour


-- 
One who is not connected with the Supreme can have neither transcendental intelligence nor a steady mind, without which there is no possibility of peace. And how can there be any happiness without peace?

http://atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810

On 3/19/12 5:01 AM, Gour wrote:
> On Sun, 11 Mar 2012 01:08:20 +0000
> Stewart Gordon<smjg_1998@yahoo.com>  wrote:
>
>> Has anybody else got further with getting logical HTML out of DDoc?
>> Have you been using DDoc to generate some internal format and then
>> some other program to turn it into HTML, or what?
>
> Excuse me for jumping into the thread, but I hope it's relevant...
>
> I wonder whether you can recommend using Ddoc for writing
> general-purpose documentation like user's manual for e.g. application
> written in D which has to be split into logical parts (chapters,
> sections,...) as well as use hyperlinking, addding pictures, tables
> etc.?
>
> Or do you believe it's better to use more specialized tool like reST
> markup with Sphinx, AsciiDoc, LaTeX/LyX...?
>
> Let me add that we'd like to have nice HTML output which can be invoked
> within application itself as well as quaility output in the form of PDF
> file.

DDoc has two main assets: (a) it understands D structures, e.g. you can use it to document D APIs, and (b) it highlights D code nicely.

Aside from that, it's a fairly simple macro system. If you don't have a need for (a)/(b), it is a passable document generation tool (pretty much as e.g. m4 would be). We use it for D's own website, and it's okay in helping with HTML generation.

More specialized tools that have a focus on document formatting have naturally an advantage over DDoc for general-purpose documentation.


Andrei

On Mon, 19 Mar 2012 09:55:40 -0500
Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:

> DDoc has two main assets: (a) it understands D structures, e.g. you
> can use it to document D APIs, and (b) it highlights D code nicely.

Yeah, that's anticpated usage of it.

> More specialized tools that have a focus on document formatting have naturally an advantage over DDoc for general-purpose documentation.

After some research, it seems that the best is to use Ddoc for documenting our code and library, while leaving the rest to the specialized tool (we're heading towards AsciiDoc).


Sincerely,
Gour


-- 
What is night for all beings is the time of awakening for the self-controlled; and the time of awakening for all beings is night for the introspective sage.

http://atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810