Re: Emacs documentation. Was My emacs was upgraded and I am a novice again

[David Kastrup]

"Dave Pawson" <dave.pawson@gmail.com> writes:

> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>
>
>
>> >> XML is not an end user format.
>> >
>> > It's the best starting point for an end user format that I've ever
>> > found.
>>
>> Correction.  "best general purpose starting point".  It is not the
>> best starting point for info, for example...
>
> If someone wanted embossable braille, or a translation system keyed
> off the language property of the instance?  Single media output is
> becoming rather dated IMHO.

If you don't cater to Emacs, you are out.  Emacs is the preferred
editor for a number of blind persons, and Emacspeak (which assumedly
cooperates with info mode) is an important tool for them.  The main
target of Texinfo is online accessible documentation: all the rest
basically is frosting on the cake.

If you don't feel you want to face the reality, you'll have a hard
time convincing developers that you offer improvements where they
_count_.

>> >> docbook2x is undocumented software.  I used it to provide a user
>> >> manual in info format for git.  It was reasonably easy to do this,
>> >> except that it was near impossible to put the respective directory
>> >> entries at the top.  After working on this a few days, I punted and
>> >> used a Perl script for post-processing the Texinfo file.  It seems
>> >> from the few uses one sees on the Web that nobody else fared
>> >> better.
>> >
>> > I've not used it so I can't comment.
>>
>> You better do so.  See below.
>
> If It's crap I'm prepared to work to improve it.

I don't say it is crap: in contrast, I stated that it apparently does
quite a good job.  But it appears to be mostly unmaintainable and
untweakable by anybody but the author.  And depending on a single
person is never a good idea.

>> Here is the problem: Richard Stallman has been quite sympathetic to
>> replacing Texinfo if a suitable alternative comes up.  It hasn't up
>> to now.
>
> According to those driving the project, clearly well within their
> comfort zone.

If you bother to comment to something, you better make it less
cryptic, or you are wasting both your own as well as your readers'
time.

>> Here are the requirements for it as far as I am concerned (I don't
>> think you have a reasonable chance to get this past Richard if the
>> following points aren't addressed satisfactorily):
>
>> a) the essential parts of the toolchain must be well-documented from a
>> documentation writer's as well as a programmer's point of view and
>> most likely copyright-assigned to the Free Software Foundation.
>
> Enough said. The group want ownership. Anothers definition of open
> not enough?

We are talking not about the definitions, but the code.

>> That  is the state of affairs with Texinfo.
>
> Clearly, since Stallman et al  developed it.
>
>> Documentation is an essential part of the GNU system.  Relying on
>> the continued goodwill of independent third parties would be a step
>> backwards from the current state of affairs.
>
> Sorry. Unfair. You're currently reliant on the good will of the
> current developers? Don't they class as independent? Eli for
> instance?

Nobody is relying on them.  The code is reasonably well-documented,
and it is copyrighted by the FSF.  So pretty much every developer can
be supplanted without development screeching to a halt.

>> This would seem to particularly apply to Docbook2X: it apparently
>> does a good job, but it is not clear what input it will accept, and
>> how a typical user could influence or extend its operation, and it
>> is written (and copyrighted) by someone who does not as a rule
>> answer Email with questions (at least I have tried and failed to
>> get a response).
>
> He's a bit cheeky with his copyright :-)
> Uses the docbook ones then copyrights them!

The Docbook definitions or actual code?

>> b) the expressivity of Texinfo must be preserved.  This concerns
>> most of the options for detailed and coarse tables of contents and
>> indices.
>
> Why? What do you want the expressivity for?  Tocs are easy enough in
> xml processing.  Ditto indexing.

If the information needed for the Info reader is no longer there, the
end user functionality is crippled.

>> c) end user access must be fast and convenient from within Emacs.
> Via current docs content?
> Generated from the XML.

Again: if you comment, do it in a manner such that more than just you
understands the comment.

>> At the current point of time, using Docbook2x for going via Texinfo
>> would mostly do the trick as a transition strategy.
>
> Why.

Because it would retain the possibility to generate Info documents as
long as Info will remain the format known to the GNU readers (Emacs
and the standalone info).

>> > My offer is to convert the emacs documentation into docbook,
>> > version 5 and work with those interested to improve it/bring it
>> > up to scratch.
>>
>> But that's the wrong way round.  At the current point of time, it
>> is not the Emacs documentation that needs to be brought up to
>> scratch, but rather the Docbook documentation, toolchain and
>> general situation.  Before that is the case, any change in the
>> source file format would be a waste of time.
>
> <chuckles/> Go RTFM. It's there.
> I'm offering my time to waste.

Again: cryptic comments like that are wasting both your and your
readers' time.

>> Experimenting with other toolchains might be easier if the Docbook
>> output of makeinfo was improved to a point where it would in most
>> cases deliver actually valid output.  Being close to
>> "roundtripping" would be a strong argument.
>
> I've never seen the logic of that argument.

It means that one can experiment with the Docbook toolchain starting
from the current existing documentation.  That makes it much easier to
judge the feasibility of transferring to a new source format.

> docbook roundtripping to word! why!  From my experience to date
> makeinfo needs a lot of work.  If its tex macros then sorry, not me.

Again: you better invest the time to make a readable comment if you
bother commenting at all.

>> > No point if the actual documenters are unwilling to move to XML
>> > though.
>>
>> As long as there is nothing in it for them, why should they?
>
> They shouldn't.
> Its for users. Not developers.
> stay comfortable folks.

So where is the benefit for the users?

>> > I've also mailed the makeinfo guy at gnu, see if the .texi to
>> > docbook can be revived. I've a nasty feeling its written in tex
>> > macros!
>>
>> As an additional note: the output of the Docbook toolchain appears to
>> be quite better than that of the Texinfo toolchain _except_ where the
>> info format is concerned: the HTML pages look nicer, the printed pages
>> possibly too (though Texinfo does a splendid job at PDF indexing).
>
> I noted that. The texi files contain the index!

No, they don't.  The info files contain the index.

> At least docbook autogenerates from index entries in the document
> body.

That's what the Texinfo toolchain does, too.  Again: where is your
point?

>> And Texinfo does not really cut it with regard to utf-8 character
>> sets.  I would still like to see evidence, though, that the
>> available Docbook toolchains do a better job where PDF, PostScript
>> or preformatted plain text are concerned (pure HTML likely should
>> work).
>
> You're wide of the mark David. Nothing to do with the toolchain.
> All down to the use of utf-8 (or 16) as the character set of XML.

But the toolchain is not XML throughout.  That's merely the source
format.

> Retain that throughout and if you have the fonts, you'll get out
> what you put in - using emacs in every mode from ASCII upwards.

As far as I know, all the XML print solutions are still using TeX, and
TeX is a strictly 8-bit engine.  So it is disingenuous to claim that
character set issues are going to magically vanish anywhere by using
XML.  XML is not the end user format.

>> So that is a definite selling point once the _primary_ purpose of
>> Texinfo, a fast user-accessible rich structured hypertext format
>> with a reasonably accessible and documented source code format to
>> people not specializing in XML, is secured.
>
> Clearly, retain status quo. OK. That's a view.

There is no point in replacing the status quo with something worse.
Yes, retaining _at least_ the status quo is a goal.  If you refuse to
aim for that, you'll never get anybody on your boat.  Doing things
differently is pointless as long as the results are not better.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum