Re: [Boost-docs] Saving space on entities with little documentation?

[Beman Dawes]

At 05:15 PM 2/4/2003, Douglas Gregor wrote:

>...If the enum has no detailed description (e.g., no
><para> elements), then we put the full definition in the synopsis and the
>purpose (if it exists) is put into a comment on the line immediately
>preceeding the definition, like this:
>
> // Enum for distinguishing parsing and formatting options.
> enum month_format_spec { month_as_integer, month_as_short_string,
> month_as_long_string };
>
>Advantages of this approach:
> 1) Less generated text (especially important for dead-tree versions)
> 2) Less jumping around for only a little documentation
> 3) Faster processing (the DocBook XSL was spending up to half its time
>grinding away at enum <refentry>'s in the Date-Time library documentation)
>
>Disadvantages of this approach:
> 1) Synopses are no longer just synopses: they contain definitions that
> may not be found elsewhere, and there will be links directly to them.
> 2) The C++ standard doesn't seem to ever do this (not that anything in
> there is described in a single sentence...)
>
>Should I do the same thing for functions? Should I back I these changes and
>not use this approach?

I'm a little afraid to comment on specific optimizations, but the general problem you describe of taking "up at least 20x the real estate" is a serious one with a lot of the generated documentation I've seen, so I think if you can optimize away unneeded indirections it will help acceptance.

While your disadvantages might be important in some contexts (like the C++ Standard) they don't seem important in the context of Boost documentation. OTOH, the advantages seem very real and worthwhile to me.

--Beman




-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs