[kde-guidelines] CVS

[Lauri Watts]

On Friday 29 October 2004 20.13, Frans Englich wrote:
> On Friday 29 October 2004 11:39, zander at kde.org wrote:
> > On Fri, Oct 29, 2004 at 02:09:09AM +0000, Frans Englich wrote:
> > > BTW, do you know if it's possible to automatically indent XML, without
> > > making space appear in inappropriate places? (link like elements etc.)
> >
> > I alsways use "xmllint --format foo.xml"  It indeed does indent properly
> > and does not indent parts with text-content between the elements.
>
> So xmllint can do that too. I used some random program called "xmlindent".
> I'll take a look.

Indenting DocBook is dangerous, since the nesting gets very deep, and there 
are elements that are rendered verbatim (including, but not limited to, 
anything in <screen>, <literallayout>, <programlisting> and <computeroutput>, 
all of which are likely to see use in this doc.  Verbatim includes leading 
whitespace, and it can lead to some very unfortunate renderings when 
something written to wrap at 80 characters (like a code snippet) is then 
indented 40 characters because it's nested so deep in the hierarchy.

I would prefer not to indent any sources.  Certainly I don't know of any 
auto-indentation tool that can manage this stuff.  Since only the maintainers 
will be committing into the source files, they should be free to indent 
things as they like (once aware of the issues, and which elements must be 
kept strictly left aligned), and since the results are autogenerated, who 
cares what they look like?

There's the secondary issue that line wrapped documents + indenting leads to 
unnecessarily massive and difficult to read diffs.

The usual rule in KDE documentation is to line wrap, and not to indent 
anything, and use newlines and white space between paragraphs to provide 
source formatting.

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20041029/78be312f/attachment.pgp