[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: not all doc "clean-ups" are good

From: Werner LEMBERG
Subject: Re: not all doc "clean-ups" are good
Date: Tue, 23 Aug 2011 07:57:32 +0200 (CEST)

>> Well, it helps in situations like this
> ...
>> which looks better with a break after the backslash:
>>      This is a  paragraph with  some text to
>>      demonstrate that a path name like /usr/
>>      local/share/lilypond/ should  be
>>      split after backslashes.
> Really?!  As an 11-year linux user, I reluctantly accept splitting a
> filename like that, but I imagine that it would confuse new linux
> users.

Another possibility is to split *before* the slash (and before the
extension dot), something which I even prefer.  For example, the
leading magazine for hobby astronomers, `Sky&Telescope', is using
this.  The new @uref implementation of the CVS version of texinfo.tex
can be configured to do that, BTW.

> I do not think those filenames should be split at all!  I prefer
> separating long filenames.

Come on, this is *completely* unrealistic!  With the same
argumentation, we must not allow long-scheme-names-like-this to be
split at the hyphens.

> This is a paragraph with some text which states that it might be a
> good idea for a user to look in:
> @example
> /usr/local/share/lilypond/
> @end example
> -----
> Doesn't this capture the best of all worlds?

I strongly disagree.  While it might be OK for really, really long
path names, the vertical disturbance of the reading flow is extremely
severe.  Just imagine that you have four such file names within a
paragraph.  You then cut such a paragraph into five chunks!  And don't
forget to insert @noindent four times to indicate that the paragraph
still continues.

> It's very readable output, it's nicely formatted (the text can use
> normal text hyphenation+formatting; the long filename has a line all
> to itself), and it's unambiguous for documentation editors to write.

This is joke, isn't it?  Looking into the documentation, this needs a
*huge* rewrite of almost everything!  Who is doing that?  My solution
is the introduction of a few `@/' after (or before) a backslash, while
yours needs @address@hidden example constructions.  My solution can be
checked with some simple regular expressions, and it doesn't really
hurt if `@/' is missing, while your suggestion needs a manual checking
of everything.

> My point is that this makes the docs harder to maintain.  We need to
> find a balance between good output and ease of editing.  Casual
> contributors are already scared away by plain texinfo; dressing
> stuff up with @/ characters is not going to help the situation.

Casual contributors should concentrate on delivering good contents!
If I had enough time to work more on LilyPond's documentation, I would
even accept plain text which I then add to the git, properly enriched
by texinfo commands by myself.  For example, I do that in groff (which
I maintain).  Later on we can guide them to improve formatting, if
such people really want to contribute more.  If I look at the many
`fix the indentation!' shouts at rietveld, I would get scared also...

> I've been reading a lot of good things about markdown; [...]

This is quite similar to the markup language used in wikis...  To get
the same expressiveness we've already reached with texinfo, I guess
that we would approximately need the same complexity with markdown.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]