help-gnu-emacs
[Top][All Lists]
Advanced

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

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


From: Tim X
Subject: Re: Emacs documentation. Was My emacs was upgraded and I am a novice again
Date: Tue, 25 Sep 2007 19:31:07 +1000
User-agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1.50 (gnu/linux)

David Kastrup <dak@gnu.org> writes:

> "Dave Pawson" <dave.pawson@gmail.com> writes:
>
>> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>>> "Dave Pawson" <dave.pawson@gmail.com> writes:
>>
>> Point taken.
>>
>>> Again, you are confusing format and reader.  The Texinfo format is
>>> archaic (but nevertheless quite alive).  The reader is what Emacs
>>> offers you.  Nobody has ever proposed a user interface that would be
>>> more efficient or convenient than Emacs' current info reader.
>>
>> Caveat. When used to it?
>
> No caveat.  When you are not used to it, you start by clicking either
> the links in the text or headers (which gives you all that HTML has to
> offer with regard to navigation) or the Info menu (which gives you
> more).
>
>>> So the source of contention is the source file format (and the
>>> compiled _fast_ info format), but that is nothing that would affect
>>> the _usage_ of the files: changing the format would probably
>>> achieve no user-visible change inside of Emacs apart from slowing
>>> it down.  At the current point of time, info access is near
>>> instantaneous.
>>
>> Can't disagree with that.
>>
>> But yes. the contention is that the source file format and end user
>> access can be improved.
>
> Both are different things.  So far, I have yet to see a proposal for
> improving the end user access that would benefit from a source file
> format change.
>
>>> 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...
>
>>> 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.
>
>>> The combined largely under- or undocumented and inscrutable
>>> layerism of XML, Docbook, Ascii2doc and Docbook2x makes it
>>> impossible to achieve a particular effect at the end of the
>>> toolchain without weeks of previous study.
>>
>> Yes. I agree. The combination is nearly as bad as sgml+dsssl+emacs
>> :)
>>
>> I've spent that time and am fairly happy with docbook, xml, xslt,
>> xsl-fo.  (I host the docbook and xslt faq )
>
> 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.  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.  That
> is the state of affairs with Texinfo.  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.  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).
>
> b) the expressivity of Texinfo must be preserved.  This concerns most
> of the options for detailed and coarse tables of contents and indices.
>
> c) end user access must be fast and convenient from within Emacs.  At
> the current point of time, using Docbook2x for going via Texinfo would
> mostly do the trick as a transition strategy.  But there would likely
> need to be some translation process (similar to producing cattable
> manpages from *roff sources) with fewer external dependencies that one
> could rely on.
>
>>> In contrast, the information for the XML toolchains is scattered
>>> all over the place and rarely in a format that can be readily
>>> browsed by humans without starting to convert and manipulate stuff
>>> first.
>>
>> Yep.
>>
>> 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.
>
> 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 sent a demo chapter to Eli for comment.
>>
>> 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?
>
>> 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).
> 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).
>
> 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.
>
> That is by no means a small job.
>

Well presented and argued David. I think the licensing point is very
important - there is no way Richard will accept the documentation format
moving to one that is not under an acceptable license i.e. one that
protects freedoms and not just one that makes it 'legal' to use. 

Tim

-- 
tcross (at) rapttech dot com dot au


reply via email to

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