all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Emacs documentation. Was My emacs was upgraded and I am a novice again
@ 2007-09-23  9:53 Dave Pawson
  2007-09-23 11:12 ` Bastien
  0 siblings, 1 reply; 19+ messages in thread
From: Dave Pawson @ 2007-09-23  9:53 UTC (permalink / raw)
  To: help-gnu-emacs

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!

regards

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

^ permalink raw reply	[flat|nested] 19+ messages in thread
[parent not found: <mailman.1178.1190541246.18990.help-gnu-emacs@gnu.org>]

end of thread, other threads:[~2007-09-29 19:42 UTC | newest]

Thread overview: 19+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-09-23  9:53 Emacs documentation. Was My emacs was upgraded and I am a novice again Dave Pawson
2007-09-23 11:12 ` Bastien
2007-09-23 11:35   ` Dave Pawson
2007-09-23 12:37     ` Bastien
2007-09-23 16:26     ` Tom Tromey
2007-09-29 15:46     ` Emacs documentation Alan Mackenzie
2007-09-29 15:47       ` Dave Pawson
2007-09-29 16:03         ` Peter Dyballa
2007-09-29 19:42         ` Alan Mackenzie
2007-09-29 16:33       ` Eli Zaretskii
     [not found]   ` <mailman.1182.1190547310.18990.help-gnu-emacs@gnu.org>
2007-09-23 12:50     ` Emacs documentation. Was My emacs was upgraded and I am a novice again David Kastrup
2007-09-23 14:55       ` Dave Pawson
     [not found]       ` <mailman.1188.1190559347.18990.help-gnu-emacs@gnu.org>
2007-09-23 15:11         ` David Kastrup
     [not found] <mailman.1178.1190541246.18990.help-gnu-emacs@gnu.org>
2007-09-23 10:58 ` David Kastrup
2007-09-23 13:02   ` Dave Pawson
     [not found]   ` <mailman.1184.1190552548.18990.help-gnu-emacs@gnu.org>
2007-09-23 13:36     ` David Kastrup
2007-09-25  9:31   ` Tim X
2007-09-24  4:41 ` Stefan Monnier
2007-09-25  9:24 ` Tim X

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.