To comment on the following update, log in, then open the issue:
http://www.openoffice.org/issues/show_bug.cgi?id=81683
Issue #|81683
Summary|<listing>'s in autodoc should allow more convenient wh
|itespacing
Component|tools
Version|OOo 2.3
Platform|All
URL|
OS/Version|All
Status|NEW
Status whiteboard|
Keywords|
Resolution|
Issue type|ENHANCEMENT
Priority|P3
Subcomponent|autodoc
Assigned to|np
Reported by|fs
------- Additional comments from [EMAIL PROTECTED] Tue Sep 18 09:32:38 +0000
2007 -------
If you currently use the <listing> element in IDL documentation, it is quite
inconvenient to enter whitespaces:
The canonical approach, used by most IDL doc writers, is
<listing>
for ( int i=0; i<n; ++i)
{
if ( foo(i) )
bar(i);
}
</listing>
However, unfortunately all those whitespaces at the beginning of the line are
eaten by autodoc, so the resulting html becomes clumsy. As an example, look at
http://api.openoffice.org/docs/common/ref/com/sun/star/resource/XResourceBundle.html:
the author of the "MyResource" class invested some effort to properly indent the
class definition, but the result just looks terrible due to missing whitespaces.
The proper solution is something like
<listing>
for ( int i=0; i<n; ++i)
{
if ( foo(i) )
bar(i);
}
</listing>
, which is a) difficult to read an maintain in the IDL source b) easy to forget
and c) inconsistent with what people are used from code documentation tools: If
I enter a code fragment in my documentation, denoting this by a special tag
(like "<code>" or "<listing>"), then I expect the tool to use this fragment
as-is, without touching it in any way. Consequently, code fragments, in other
tools, are usually enclosed in a <pre></pre> pair, which preserves the layout of
the documentation writer.
autodoc should do so, too. <listing> is intended for multi-line code fragments
(so I understand it, though
http://api.openoffice.org/docs/DevelopersGuide/Appendix/IDLDocumentationGuide/IDLDocumentationGuide.xhtml
is not very explicit here), and those should be enclosed in a <pre> tag.
Note that this change can be done with touching only a few IDL files - most
files which currently use <listing> do *not* use the tags at all.
---------------------------------------------------------------------
Please do not reply to this automatically generated notification from
Issue Tracker. Please log onto the website and enter your comments.
http://qa.openoffice.org/issue_handling/project_issues.html#notification
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
