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

[Tim X]

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

> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>> "Dave Pawson" <dave.pawson@gmail.com> writes:
>
>> One does not get acquainted with Emacs' editing by reading its C and
>> Lisp source code either.  The documentation system of Emacs is _info_
>> as far as online access is concerned.  The .texi files are not
>> intended for reading, but for writing.  It is source code.
>
> One does if one believes they can be improved.
>
>
>>
>> So I really repeat the recommendation to get acquanted with the info
>> reader in Emacs.  It puts the information at your fingertip, and the
>> .texi files don't do that.
>
> 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?
>
>  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.
>
>
>
>> XML is not an end user format.
>
> It's the best starting point for an end user format that I've ever found.
>
>
>
>> 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.
>
>
>
>
>> 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 )
>
>
>>
>> While the toolchain may be in better shape (I found it to produce
>> pretty much perfect Texinfo from the get-go while Texinfo's Docbook
>> output was ill-formed), it is just not usable without months of study
>> and fishing for information in distributed places.
>
>
>
>>
>> Coming back to the manual page problem: in Texinfo, this could be
>> solved easily using @include and @raisesections, consulting just a
>> single manual about a single format, a well-structured and indexed
>> manual that can be browsed efficiently in Emacs even on slow machines.
>
> Which is a solution to the last issue.
> From an XML source I could identify and write out small files needed
> by the elisp for inclusion where needed (even language specific if
> needs be).
>
>
>
>
>
>>
>> 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.
>
> I've sent a demo chapter to Eli for comment.
>
> No point if the actual documenters are unwilling to move to XML though.
>
> 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!
>

Its great you are willing to put in all the effort to try and move things
over. However, I'm skeptical about the results we will get. 

While XML has great power, DK is correct that getting to grips with a
markup definition like docbook is much much harder than writing
texinfo. The basic markup isn't too hard to get use to, but the knowledge
required to process it into different presentation formats is really quite
a task. I really like the flexibility XML markup offers (though I'm getting
very tired of everyone thinking its a magic bullet to every problem - but
thats another gripe I'll leave ... for now). On some levels, docbook is
more 'pure' because of its cleaner seperation of content from
presentation. Texinfo is a bit mixed - it has markup that is content
defining, but it also mixes in markup which is presentation oriented. 

both approaches have pros and cons. Docbook has the promise of providing a
markup that can truely be processed to give us different presentation
formats in a consistent manner. However, it has a steeper learning curve
and while modes like nxml make it fairly easy to use, its still harder for
people to adjust to (have we all been ruined by wysiwyg editors?). 

Texinfo does info pages really well and some other well defined formats,
but isn't going to give you a standard 'quality' over different
presentation formats and has a more restrictive set of formats that it
supports. However, its easier to rite in, easier to format into one of its
presentation forms and has some other nice features that make it pretty
good for working with emacs. 

One of the advantages of info is its fast and close integration with
emacs. Any change in documentation format will need to preserve this. If
the sources can be moved to being XML based and we still get as good a
quality format in the info pages, then it may get enough support to be
maintained. However, I think this is going to be where things will fall
apart. The format that is used has to be one that those who maintain the
documentation are willing to switch to. One problem that I can see, (apart
from convincing people to learn docbook or whatever) is that markup
definitions like docbook are usually a *lot* richer in supported markup
tags than texinfo. People will find this confusing and as the documentation
is likely maintained by multiple people, there will need to be some sort of
style guide that reduces the choices to ensure a consistent look and feel
once it is processed to a particular format, such as info. 

One of the most common problems I've encountered when trying to get people
to use docbook is that they find the choices in tags overwhelming. There
are a number of 'stripped down' docbook based definitions that attempt to
resolve this problem by only defining a subset of all the defined docbook
tags. It may be something that is worth looking into for this task.

Tim




-- 
tcross (at) rapttech dot com dot au