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

[Dave Pawson]

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.

>
> >> 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.



> 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.


 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?

> 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?


 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!



>
> 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.



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

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

Why.



> > 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.






>
> 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. docbook roundtripping to word! why!
>From my experience to date makeinfo needs a lot of work.
If its tex macros then sorry, not me.



> > 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.


>
> > 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!
At least docbook autogenerates from index entries in the document body.

> 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.
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.



>
> 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.

regards



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk