View mode: basic / threaded / horizontal-split · Log in · Help
March 11, 2012
Re: DDoc and logically structured HTML
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.
March 12, 2012
Re: DDoc and logically structured HTML
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.
March 12, 2012
Re: DDoc and logically structured HTML
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.
March 12, 2012
Re: DDoc and logically structured HTML
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.
March 19, 2012
Ddoc as general documentation tool (was Re: DDoc and logically structured HTML)
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
March 19, 2012
Re: Ddoc as general documentation tool (was Re: DDoc and logically structured HTML)
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
March 19, 2012
Re: Ddoc as general documentation tool
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
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home