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

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:
> "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

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

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Bastien]

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

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

It would be like trying to convert man pages into docbook. Why?

I guess too many developpers actually use Texinfo to document their
code, and both users and developpers seem to be happy with that.

-- 
Bastien

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

[Dave Pawson]

On 23/09/2007, Bastien <bzg@altern.org> wrote:
> "Dave Pawson" <dave.pawson@gmail.com> writes:
>
> > 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.
>
> It would be like trying to convert man pages into docbook. Why?

Because XML is more flexible and a more modern standard for documentation IMHO.

>
> I guess too many developpers actually use Texinfo to document their
> code, and both users and developpers seem to be happy with that.


You may be right. I think it is worth challenging though, otherwise
we'll never progress?


regards

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

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

[Bastien]

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

>> I guess too many developpers actually use Texinfo to document their
>> code, and both users and developpers seem to be happy with that.
>
> You may be right. I think it is worth challenging though, otherwise
> we'll never progress?

Progress in itself doesn't say that much, it's rather a matter of where
we want to progress to...

-- 
Bastien

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, Bastien <bzg@altern.org> wrote:
>> "Dave Pawson" <dave.pawson@gmail.com> writes:
>>
>> > 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.
>>
>> It would be like trying to convert man pages into docbook. Why?
>
> Because XML is more flexible and a more modern standard for
> documentation IMHO.

If I break my arm it is also more flexible.  The question is what
tanglible, user-visible benefit you expect to be coming from the
purported added flexibility.  We don't have the developer power to
chase after every "modern standard".  If we did, we would have had to
convert the whole GNU documentation from Texinfo to HTML to SGML to
Linuxdoc to XML/Docbook by now, without tangible benefit of any such
change.

You are proposing to have a lot of work done in order to be more
buzzword compliant.  Unless you come up with some very good _visible_
benefits, you will be rather alone with that work.  And then you still
face the challenge of convincing people they should change to your
version when you are done.

>> I guess too many developpers actually use Texinfo to document their
>> code, and both users and developpers seem to be happy with that.
>
> You may be right. I think it is worth challenging though, otherwise
> we'll never progress?

Progress without aim is just activism.  You need to balance benefits
and efforts.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

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

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:


> If I break my arm it is also more flexible.  The question is what
> tanglible, user-visible benefit you expect to be coming from the
> purported added flexibility.

Forget it David. Wouldn't want to upset you.


>
> You are proposing to have a lot of work done

No, I was offering to do a lot of work.


>
> >> I guess too many developpers actually use Texinfo to document their
> >> code, and both users and developpers seem to be happy with that.
> >
> > You may be right. I think it is worth challenging though, otherwise
> > we'll never progress?
>
> Progress without aim is just activism.  You need to balance benefits
> and efforts.

Against stagnation.






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

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:
>
>
>> If I break my arm it is also more flexible.  The question is what
>> tanglible, user-visible benefit you expect to be coming from the
>> purported added flexibility.
>
> Forget it David. Wouldn't want to upset you.

If you don't upset anybody by explaining user-visible benefits, you
won't get into a position to upset the current way of doing things.

>> You are proposing to have a lot of work done
>
> No, I was offering to do a lot of work.

Sure, and that is appreciated.  But it would be unrealistic to expect
that you will do all of the work to convert all of GNU to a new
document format and maintain all of that documentation in all
eternity.  So without a favorable cost/benefit estimate, you can't
expect people to jump on your boat.

And if you are fully prepared to do _all_ of the work, go ahead.
Nobody is keeping you from it.  You'll still need to convince people
in the end that they are better off using your work than what they had
previously.

>> >> I guess too many developpers actually use Texinfo to document
>> >> their code, and both users and developpers seem to be happy with
>> >> that.
>> >
>> > You may be right. I think it is worth challenging though,
>> > otherwise we'll never progress?
>>
>> Progress without aim is just activism.  You need to balance benefits
>> and efforts.
>
> Against stagnation.

Fine warcry, but we are talking about Emacs here, software close to
its 30th birthday, and GNU, inspired by ancient UNIX systems.  Of
course, you can just go ahead: "code talks" is a mantra not unheard of
in these circles.  Being able to demonstrate a working implementation
always improves your chances of acceptance.  But not to 100%.  Whether
or not you want to explain them, there need to be tangible benefits.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Tom Tromey]

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

Dave> Because XML is more flexible and a more modern standard for
Dave> documentation IMHO.

But consider the current situation: there is a lot of Texinfo source
throughout the GNU suite; it is known by many GNU developers; tools
(well, one tool: makeinfo) for generating output from it exist and
work pretty well; and the output is in wide use in a variety of
formats.

This means there is a lot of inertia.  Any proposed change has to
carry with it a large, tangible benefit -- precisely because the cost
of switching is so high.


Personally, I like Texinfo well enough, though honestly I don't really
relish writing in any documentation format :-).

I still use info every day; I've always suspected that the vocal
anti-info contingent out there has never really given it a try :}.

Tom

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

[Stefan Monnier]

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

It would be more constructive to tell us which part of the Info reader you
found confusing or lacking.  It used to be a bit tricky to use back when it
didn't support mouse-clicks to follow links, but nowadays I find it to work
largely like web-browsers do, just with better search capabilities and while
using a tiny fraction of the memory (and time) taken by Firefox to display
html documentation.

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

Requirements:
1 - the documentation should be readable on-line from within Emacs.
2 - from a Linux/xterm/PuTTY console as well.
3 - make sure it's as easy to write docbook with Emacs than it is to write
    Texinfo.
4 - have convincing arguments about why docbook is superior.
5 - of course the documentation should also be usable without a screen
    (e.g. emacspeak).
6 - All of the above with tools covered at least by a Free Software license,
    or maybe even with the copyright transferred to the FSF.

There may be a few more, but I think it's a good starting point.
Number 1 means either a robust Docbook->Info translator, or a new elisp
package which renders Docbook (or some other intermediate format generated
from Docbook) directly in Emacs on the fly.  This could potentially use
a bit of C-level coding, linking to xml-processing libraries as long as they
are sufficiently widely supported.
And of course, the features should be a superset, so we need at least a good
indexing system and a full-body search.

> No point if the actual documenters are unwilling to move to XML though.

I don't think it's impossible to make them move, but there's going to be
a lot of resistance: just like in nature you see species which may seem just
"inferior" but they have their niche and they have developed specific
features we just don't understand which makes them better suited in
those niches.


        Stefan

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

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

[Tim X]

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