Re: INFO on add-ons

Re: INFO on add-ons

[Alex Schroeder]

"David A. Cobb" <superbiskit@cox.net> writes:

> Would nearly everyone agree that folks who provide/maintain packages
> or FSF Emacs add-ons ought to consider it a professional obligation to
> provide an Info source covering their software, and that any
> installation process ought to support this by merging these
> (INSTALL-INFO)  with the Emacs Info.Dir?

Not me.

Re: INFO on add-ons

[David A. Cobb]

Alex Schroeder wrote:

>"David A. Cobb" <superbiskit@cox.net> writes:
>
>  
>
>>Would nearly everyone agree that folks who provide/maintain packages
>>or FSF Emacs add-ons ought to consider it a professional obligation to
>>provide an Info source covering their software, and that any
>>installation process ought to support this by merging these
>>(INSTALL-INFO)  with the Emacs Info.Dir?
>>    
>>
>
>Not me.
>

Y? please.

>  
>
-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: INFO on add-ons

[Alex Schroeder]

"David A. Cobb" <superbiskit@cox.net> writes:

> Alex Schroeder wrote:
>
>>Not me.
>
> Y? please.

Most of the code I write fits into an elisp file.  Instead of writing
texinfo, and worrying about correct installation, and copyright info,
and layouting, and cross references, I would rather just put the stuff
in the Commentary section, and provide as much help as possible in the
defgroup, defcustom, and defun statements.  These docstrings are what
programmers and users use in their daily life.  The manuals are not
used very often.  They are nice to have for newbies, and for
user-level features that are distributed over a big number of
functions (such as how keymaps work, how extents work, how to write a
regexp, how to navigate in a buffer, etc.).

When I write sql.el, for example, I could copy and paste some stuff
into a texinfo file.  But keeping the stuff in sync would be even
worse than keeping the Commentary in sync with the rest.  The same is
true for color-theme.el, ansi-color.el, master.el, etc.

Actually, to be honest, I find the Emacs Wiki at emacswiki.org to be a
wonderful compromise.  I can put basic user-level docs there, and
other people can contribute but just editing the pages and typing.  No
fuss about texinfo, copyrights, LaTeX, info, xref, etc.  It just
works.  For me.  :)

Alex.

Re: INFO on add-ons

[Alex Schroeder]

Alex Schroeder <alex@emacswiki.org> writes:

> I would rather just put the stuff in the Commentary section, and
> provide as much help as possible in the defgroup, defcustom, and
> defun statements.  These docstrings are what programmers and users
> use in their daily life.

I forgot to mention this: Emacs is supposed to be a self-documenting
editor.  Therefore, we should try to support that notion.  Only if doc
strings and commentaries (readable via package finder in Emacs,
perhaps there needs to be a better interface?) fail, should we need to
write Info.  As I said this is for newbies, and pulling stuff
together.

Alex.

Re: INFO on add-ons

[Miles Bader]

Alex Schroeder <alex@emacswiki.org> writes:
> Only if doc strings and commentaries (readable via package finder in
> Emacs, perhaps there needs to be a better interface?) fail, should we
> need to write Info.  As I said this is for newbies, and pulling stuff
> together.

I use doc-strings more often in my daily work, but I think info files
are very useful for getting a broader view of a package.  I don't think
we should avoid writing manual entries just because there are
doc-strings (and the package finder is so pathetic that it's not really
much of a contender for anything; at best, it's a way of seeing a list
of what packages there are).  Other source of documentation tend to be
scattered all over the place, and would be much more useful if they
were pulled together -- and what better way than by using info (perhaps
automatically generated info)?

Usually when I write manual entries I mostly copy the doc-strings I
wrote earlier, make mechanical changes like replacing FOO with
@var{foo}, and change the wording slightly to fit the manual format
better (e.g., remove duplicate text that can be shared more easily in
the manual page).

Perhaps what we ought to do is make it easier to produce a coherent
info node(s) from a package's existing information.

E.g., if we could automatically take the `;;; Commentary:' header from
and the doc-strings an elisp file, and massage them appropiately,
maybe the result would be a good start for making an info node.  Like
checkdoc, but even more whizzy (call it `makedoc' :-)...

The problem, of course, is that the elisp file will get updated later,
and if you re-run `makedoc' you'll have to go and re-do all the cleanup
you had to do the last time, so anything we could do to make the
automatic result better would be good.  [note that currently it's very
common for doc-strings and manual entries to go out of sync, though]

One thing that might make the job easier would be embedding various
formatting directives in doc-strings, which would be removed or
intepreted at display-time by the help commands (I think computers are
fast enough these days that this wouldn't be a problem), and could be
used to perform more coherent documentation.  A simple example would be
allowing the use of texinfo forms like @var{foo} or @code{foo} in
doc-strings.

An alternative to the above might be a real on-demand info-page creator
that would prodce more `mechanical' results than a real manual, but
could still benefit from all the power of the info browser (which
really is a good tool; we should use it!).  [I've long thought that the
current `package browser' should be replaced by automatically generated
info nodes.]

-Miles
-- 
Suburbia: where they tear out the trees and then name streets after them.

Re: INFO on add-ons

[Eli Zaretskii]

On 4 Sep 2002, Miles Bader wrote:

> Usually when I write manual entries I mostly copy the doc-strings I
> wrote earlier, make mechanical changes like replacing FOO with
> @var{foo}, and change the wording slightly to fit the manual format
> better (e.g., remove duplicate text that can be shared more easily in
> the manual page).
> 
> Perhaps what we ought to do is make it easier to produce a coherent
> info node(s) from a package's existing information.

Adding index entries is a significant task of writing a good manual.  
Without an index, a manual cannot be used as a reference.  Indexation is 
still largely a human task that cannot be easily automated (although some 
help here would be nice).

Re: INFO on add-ons

[Miles Bader]

Eli Zaretskii <eliz@is.elta.co.il> writes:
> > Perhaps what we ought to do is make it easier to produce a coherent
> > info node(s) from a package's existing information.
> 
> Adding index entries is a significant task of writing a good manual.  
> Without an index, a manual cannot be used as a reference.  Indexation is 
> still largely a human task that cannot be easily automated (although some 
> help here would be nice).

There's no reason why indexing command couldn't be embedded in
doc-strings/comments.

-Miles
-- 
Run away!  Run away!

Re: INFO on add-ons

[Eli Zaretskii]

On 4 Sep 2002, Miles Bader wrote:

> Eli Zaretskii <eliz@is.elta.co.il> writes:
> > > Perhaps what we ought to do is make it easier to produce a coherent
> > > info node(s) from a package's existing information.
> > 
> > Adding index entries is a significant task of writing a good manual.  
> > Without an index, a manual cannot be used as a reference.  Indexation is 
> > still largely a human task that cannot be easily automated (although some 
> > help here would be nice).
> 
> There's no reason why indexing command couldn't be embedded in
> doc-strings/comments.

Right.  However, my point was that coming up with the index entries is 
not a job for a program, it requires human intervention.

Re: INFO on add-ons

[Miles Bader]

Eli Zaretskii <eliz@is.elta.co.il> writes:
> > There's no reason why indexing command couldn't be embedded in
> > doc-strings/comments.
> 
> Right.  However, my point was that coming up with the index entries is 
> not a job for a program, it requires human intervention.

Sure, but since the `automatic' step I was talking was transforming
doc-strings/comments -> info nodes, embedding such commands would avoid
the problem of automatic index generation.

In addition, they would be useful without info as well, makeing it
possible to have a `doc-string index', which might be more useful than
a simple apropos in many cases.

-Miles
-- 
I have seen the enemy, and he is us.  -- Pogo

Re: INFO on add-ons

[Eli Zaretskii]

On 4 Sep 2002, Miles Bader wrote:

> Eli Zaretskii <eliz@is.elta.co.il> writes:
> > > There's no reason why indexing command couldn't be embedded in
> > > doc-strings/comments.
> > 
> > Right.  However, my point was that coming up with the index entries is 
> > not a job for a program, it requires human intervention.
> 
> Sure, but since the `automatic' step I was talking was transforming
> doc-strings/comments -> info nodes, embedding such commands would avoid
> the problem of automatic index generation.

Yes, but that means we need to go over all the doc strings and add the 
indexing commands.  A lot of work.

Re: INFO on add-ons

[Miles Bader]

On Wed, Sep 04, 2002 at 03:20:05PM +0200, Eli Zaretskii wrote:
> > Sure, but since the `automatic' step I was talking was transforming
> > doc-strings/comments -> info nodes, embedding such commands would avoid
> > the problem of automatic index generation.
> 
> Yes, but that means we need to go over all the doc strings and add the 
> indexing commands.  A lot of work.

It hardly matters -- for commands that are not already documented in info, it
would have to be done anyway, and would be no more work that doing the same
for a texinfo doc.  For commands tha _are_ documented we've already got a
source of indexing information: the info docs!

[but since I'm talking about this in the context of producing documentation
for currently undocumented code, I presume mostly it would be the former]

In any case, I think you're overemphasizing the importance and difficulty of
indexing just a wee bit; after all, programming reference documentation is
different in many ways than documents in general (it's much more regular, for
one thing), and the _most_ important index entries (the commands and
functions being documented) probably _can_ be generated automatically.

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: INFO on add-ons

[Eli Zaretskii]

On Wed, 4 Sep 2002, Miles Bader wrote:

> In any case, I think you're overemphasizing the importance and difficulty of
> indexing just a wee bit; after all, programming reference documentation is
> different in many ways than documents in general (it's much more regular, for
> one thing), and the _most_ important index entries (the commands and
> functions being documented) probably _can_ be generated automatically.

I think good indices are extremely important.  Without them, a large 
manual cannot be efficiently used as a reference, since text-based search 
is too limited, especially when the subject string you look for is not 
included verbatim in the text.

In my experience, indexing functions, commands, and variables, while 
important, is not enough to have a good index.  You need a good concept 
index where users can look up subjects that are not in the text.  As an 
example, consider an index item "cut and paste" in the Emacs manual.

Re: INFO on add-ons

[Valdis.Kletnieks]

[-- Attachment #1: Type: text/plain, Size: 809 bytes --]

On Thu, 05 Sep 2002 06:46:08 +0200, Eli Zaretskii said:
> In my experience, indexing functions, commands, and variables, while 
> important, is not enough to have a good index.  You need a good concept 
> index where users can look up subjects that are not in the text.  As an 
> example, consider an index item "cut and paste" in the Emacs manual.

Amen.

'C-h a' does a fairly good job of describing the trees.  It does a truly
horrid job of describing the forest.

For example, setting zmacs-region to nil will affect the setting of the
X selection - and will also affect the behavior of M-u (whether to do
a word or region).  Lotta forest there.

Custom - I've never decided for sure there's any actual trees in there. ;)


-- 
				Valdis Kletnieks
				Computer Systems Senior Engineer
				Virginia Tech


[-- Attachment #2: Type: application/pgp-signature, Size: 226 bytes --]

Re: INFO on add-ons

[Robert J. Chassell]

   In my experience, indexing functions, commands, and variables, while 
   important, is not enough to have a good index.  You need a good concept 
   index....

Eli Zaretskii is 100% right.  Also, you need to describe your entries
in more than one way, not only as `Cut and Paste', but also `Paste,
Cut', since people look things up in different ways.  (I just noticed
that the Emacs manual lacks `Paste, Cut' .... :-( ).

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Alex Schroeder]

Miles Bader <miles@lsi.nec.co.jp> writes:

> Alex Schroeder <alex@emacswiki.org> writes:
>> Only if doc strings and commentaries (readable via package finder in
>> Emacs, perhaps there needs to be a better interface?) fail, should we
>> need to write Info.  As I said this is for newbies, and pulling stuff
>> together.
>
> I use doc-strings more often in my daily work, but I think info files
> are very useful for getting a broader view of a package.  I don't think
> we should avoid writing manual entries just because there are
> doc-strings

Totally correct.  That is what I meant by "pulling stuff" together.
The idea of writing a texinfo page for every package, however, is
overkill.  We only need a texinfo page when a broader view of a
package is required.  In sql.el, for example, there is a sql-help
defun, and all the entry points have enough information to get you
started.  And it is not so complex as to merit a manual.

I am not saying a manual is useless.  I am saying that requiring a
manual at all times is useless.

Alex.

Re: INFO on add-ons

[Richard Stallman]

    E.g., if we could automatically take the `;;; Commentary:' header from
    and the doc-strings an elisp file, and massage them appropiately,
    maybe the result would be a good start for making an info node.

A real manual is nothing like a collection of doc strings.  If you use
the doc strings as a starting point for writing a manual, you will
have to do a lot of rewriting to make it into a good manual.

    The problem, of course, is that the elisp file will get updated later,
    and if you re-run `makedoc' you'll have to go and re-do all the cleanup
    you had to do the last time,

Rewriting the doc strings into a real manual is a lot of work.  Nobody
who has done this job properly would consider redoing it just because
the doc strings have changed.  It is much less work to update the
manual directly, and that's what people do.

If you are using `makedoc' over and over, for different versions of
one program, you are not using it right.

				 so anything we could do to make the
    automatic result better would be good.

This would be a grave mistake, because it would encourage people to
use the output of `makedoc' as a manual itself, without the necessary
rewriting to make a good manual.

In fact, I think that having a `makedoc' at all is a grave mistake
for the same reason.  Assuming you intend to write a manual starting from
doc strings, the work of collecting them from a .el file is nothing
compared with the work of rewriting them.

What I think might be useful would be a mode with interactive commands
that help convert from doc string style to Texinfo style.  They would
have to be interactive commands, because there is not enough info in a
doc string to produce proper Texinfo automatically.  Suitable commands
could make this editing task easier, but could not make it automatic.

As for indexing in doc strings, that might perhaps be a useful help
feature in its own right, and it might be worth implementing for that
reason, but that alone won't make `makedoc' produce adequate output.

Re: INFO on add-ons

[Pavel Janík]

   From: Miles Bader <miles@lsi.nec.co.jp>
   Date: 04 Sep 2002 10:39:37 +0900

   > [I've long thought that the current `package browser' should be
   > replaced by automatically generated info nodes.]

And it is also mentioned in our TODO file:

* Replace finder.el with something that generates an Info file
  which gives the same information through a menu structure.  [Dave
  Love started on this.]
-- 
Pavel Janík

It's an editor, a programming environment, a mail and news reader, a
shrink, and a way of life.
                  -- Eli Zaretskii in gnu.emacs.help about Emacs

Re: INFO on add-ons

[Eli Zaretskii]

On Wed, 4 Sep 2002, Alex Schroeder wrote:

> I forgot to mention this: Emacs is supposed to be a self-documenting
> editor.

An Info manual doesn't contradict that notion.  Whether the documentation 
text is part of the code or not is IMHO immaterial as long as you have 
commands that e.g. take you from a symbol in the source to its 
documentation.

Re: INFO on add-ons

[Robert J. Chassell]

Alex Schroeder <alex@emacswiki.org> wrote:

   I forgot to mention this: Emacs is supposed to be a self-documenting
   editor.  

Right.  That is why it has such a good Info and other help system.

Please remember, even a good distribution, such as Debian, distributes
the .el files in a separate package that many people do not load.

This is the Debian .el installation:

    apt-get install emacs21-el 

i.e., the .el files are not part of package that you install with:

    apt-get install emacs21

Also, please remember that novices often do *not* know that .el files
exist.  Worse, when they learn about them, the .el files sound scary.
A goal is to lead those novices who want to use Emacs as more
than a useful tool to the .el files.  

The kind of people who want a useful tool, and no more, might, if
persuaded, read the Info or other online help, such as that provided
by Control-h; but they do not have the interest or the time to do
more, unless very gently persuaded.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Eli Zaretskii]

On Wed, 4 Sep 2002, Alex Schroeder wrote:

> Most of the code I write fits into an elisp file.  Instead of writing
> texinfo, and worrying about correct installation, and copyright info,
> and layouting, and cross references, I would rather just put the stuff
> in the Commentary section, and provide as much help as possible in the
> defgroup, defcustom, and defun statements.  These docstrings are what
> programmers and users use in their daily life.  The manuals are not
> used very often.

The doc strings have a disadvantage that they lack a broader context.  
That is, a doc string documents its parent object, and sometimes a small 
number of related objects, but it doesn't give you a large-scale view.

Comments are nice, but they lack an efficient mechanism for looking up 
the information.

Texinfo solves these problems (the latter one is solved via index-search 
and other ways of searching Info manuals).

So a well-indexed Texinfo manual is IMHO a necessary element of 
documenting software.

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "David" == David A Cobb <superbiskit@cox.net> writes:

    David> Would nearly everyone agree that folks who provide/maintain
    David> packages or FSF Emacs add-ons ought to consider it a
    David> professional obligation

_Obligation_?  Not.

Of course good documentation is one of the policy goals of all free
software projects.  But the users who volunteer their time and
intellectual property have the right to set their own priorities.

    David> to provide an Info source covering their software, and that
    David> any installation process ought to support this by merging
    David> these (INSTALL-INFO) with the Emacs Info.Dir?

That's a maintenance nightmare, and often impossible on real OSes
where not everyone is root.  What's wrong with the current (XEmacs
only?) system which automatically generates Dir from the info-path?
All this requires is adding a specially-marked menu description to
each texinfo source.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Miles Bader]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
>     David> to provide an Info source covering their software, and that
>     David> any installation process ought to support this by merging
>     David> these (INSTALL-INFO) with the Emacs Info.Dir?
> 
> That's a maintenance nightmare

How so?  It seem to work well enough if people consistently use
`install-info' (and that actually seems to happen on debian at least).

> and often impossible on real OSes where not everyone is root.

People certainly have write access to the `dir' file in any directory
they write info files to.  Since info merges all the different `dir'
files into the final buffer at run-time, that's all that's needed.

> What's wrong with the current (XEmacs only?) system which
> automatically generates Dir from the info-path?

I'm not sure exactly what you mean; as I mentioned above, emacs merges
all the various `dir' files.

-Miles
-- 
I have seen the enemy, and he is us.  -- Pogo

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Miles" == Miles Bader <miles@lsi.nec.co.jp> writes:

    Miles> "Stephen J. Turnbull" <stephen@xemacs.org> writes:

    David> to provide an Info source covering their software, and that
    David> any installation process ought to support this by merging
    David> these (INSTALL-INFO) with the Emacs Info.Dir?

    >> That's a maintenance nightmare

    Miles> How so?  It seem to work well enough if people consistently
    Miles> use `install-info' (and that actually seems to happen on
    Miles> debian at least).

I have no control over "people", and little enough over XEmacs.
Better to spend the effort on having Emacs be smart about the info
files themselves, which either it can read or it doesn't matter, than
to have GNU and XEmacs.ORG try be anal about stuff that's not under
our control.  IMO.

    >> and often impossible on real OSes where not everyone is root.

    Miles> People certainly have write access to the `dir' file in any
    Miles> directory they write info files to.  Since info merges all
    Miles> the different `dir' files into the final buffer at
    Miles> run-time, that's all that's needed.

That's fine, but I got the impression David was talking about the
specific dir file in the info directory where Emacs stuff resides.
What you're describing is just a "pre-caching" version of XEmacs's
current strategy.

    >> What's wrong with the current (XEmacs only?) system which
    >> automatically generates Dir from the info-path?

    Miles> I'm not sure exactly what you mean; as I mentioned above,
    Miles> emacs merges all the various `dir' files.

AFAIK, install-info looks at @dircategory and @direntry.  Well, so
does XEmacs, and it gives them priority over dir.  The main issue here
is time spent in gunzip (and I'm not sure if that is anything but
process overhead, ie, with a zlib-capable Emacs this might go away),
otherwise it works well.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Miles Bader]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
> Better to spend the effort on having Emacs be smart about the info
> files themselves, which either it can read or it doesn't matter, than
> to have GNU and XEmacs.ORG try be anal about stuff that's not under
> our control.

From my point of view (debian with some random stuff compiled from
source in /usr/local), everything seems to work pretty well as-is.

Maybe others have a different story.

-Miles
-- 
"I distrust a research person who is always obviously busy on a task."
   --Robert Frosch, VP, GM Research

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Miles" == Miles Bader <miles@lsi.nec.co.jp> writes:

    Miles> "Stephen J. Turnbull" <stephen@xemacs.org> writes:

    >> Better to spend the effort on having Emacs be smart about the
    >> info files themselves, which either it can read or it doesn't
    >> matter, than to have GNU and XEmacs.ORG try be anal about stuff
    >> that's not under our control.

    Miles> From my point of view (debian with some random stuff
    Miles> compiled from source in /usr/local), everything seems to
    Miles> work pretty well as-is.

You're a low-maintenance kinda guy, Miles.  ;-)  Considering that
(AFAIK) install-info was originally written for Debian by Ian Jackson
(and on my Debian systems it is still part of dpkg, not info or
texinfo), it's hardly surprising that it works on Debian.[1]

However, there is no "the" install process.  We have ours, you have
yours, upstream Lisp maintainers have theirs, Debian has its Emacs
Policy, the HP/UX Porting Centre has its own way, etc.  In the face of
that, I don't see how to guarantee that install-info will get run.  If
I don't have to, I don't want to think about it, either.

OTOH, if you run XEmacs, you will get a sensible Info Dir node, or
your money back.  ;-)  The approach I'm talking about _is_ "as-is" on
XEmacs, which works pretty well for us, too.  When we notice a problem
with indexing of an Info file we distribute, we patch the source with

+@dircategory ...
+@direntry ...
+ [...]
+@end direntry

This is invariably accepted immediately upstream, and if not, it is
trivial to maintain.  One problem + one patch = one solution---and no
thought required.  Maintainer Heaven!



Footnotes: 
[1]  Note also that Debian goes to extreme lengths to insure
cooperation of packages it distributes among themselves, and where
possible interoperation with other systems.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[David A. Cobb]

Stephen J. Turnbull wrote:

>Footnotes: 
>[1]  Note also that Debian goes to extreme lengths to insure
>cooperation of packages it distributes among themselves, and where
>possible interoperation with other systems.
>  
>
Um, you aren't saying this is a bad thing, are you Stephen?
However a volunteer project likely can't take _extreme_ measures.  It 
requires to enlist the positive co-operation of the contributors.  And 
I'm well aware that some won't ever comply.  Even when the documentation 
is "gold-plated" I was involved once in a gov't acquisition where we 
were frankly told "our programmers would rather quit than write C-Specs 
(Detailed Program Design Docs)."  I was not in charge or I might have 
said that would be a benefit to the whole industry.

-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

"Extreme Documentation" [was: INFO on add-ons]

[Stephen J. Turnbull]

>>>>> "David" == David A Cobb <superbiskit@cox.net> writes:

    David> Stephen J. Turnbull wrote:

    >> Footnotes: [1] Note also that Debian goes to extreme lengths to
    >> insure cooperation of packages it distributes among themselves,

    David> Um, you aren't saying this is a bad thing, are you Stephen?

No.  Merely that Debian users are highly unlikely to pose the kinds of
problems that I'm thinking about when I write "nightmare".  This
serves Debian's purposes well, but among Linux and *BSD distros, it
_is_ extreme.

    David> However a volunteer project likely can't take _extreme_ measures.

Debian can and does (the Emacs Policy), as does the GNU Project (the
FSF assignment policy[1]).  The question is do the benefits justify the
discouragement of contributions?  And that largely depends on the
contributors' perception of need for the measures.

The problem with more strict documentation requirements is not that
programmers see no need for documentation, or even no need for user-
level documentation.  The problem is that most of it is already
available in docstrings, so that creation of reasonably complete
functional documentation _could_ (at least in theory) be automated.
It certainly could be done by users (a) with only limited amounts of
time or (b) with only limited acquaintence with the implementation.

And one of the most frustrating things for any maintainer is a post of
the form "it took me two hours to figure out how to do X, but I
finally did.  No thanks to the crummy docs!"  And no thanks to you,
either, for not telling us what you learned....  Users have a lot of
information that the maintainers do not know.  Aggregating that would
be very useful, but how?  FAQs are traditional, of course, and Wikis a
more modern route.  But these tend to take on a life of their own, and
not get integrated into the distributed manuals and other docs.

These alternative means of generating documentation undermine the
perception of need for documentation by the programmers themselves.
So it's hard to generate a consensus for a draconian docs policy.  Nor
does "encouragement" work well; programmers, with much justification,
feel that their code contributions deserve weight and that they are
already contributing sufficiently to documentation.


Footnotes: 
[1]  "Extremism in the defense of freedom is no vice."  By the test of
comparison with other projects, it is nonetheless extreme.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: "Extreme Documentation" [was: INFO on add-ons]

[David A. Cobb]

Stephen J. Turnbull wrote:

>"David" == David A Cobb <superbiskit@cox.net> writes:
>  
>
>The problem is that most of it is already
>available in docstrings, so that creation of reasonably complete
>functional documentation _could_ (at least in theory) be automated.
>
Yeah, I thought of that.  Needs to bubble around a bit in my head before 
speaking.

>It certainly could be done by users (a) with only limited amounts of
>time or (b) with only limited acquaintence with the implementation.
>
F'rinstance: I have huge quantities of time available and I'm a better 
than average wordsmith.  Getting organized is a problem, and misleading 
documentation is worse than none at all.

>These alternative means of generating documentation undermine the
>perception of need for documentation by the programmers themselves.
>So it's hard to generate a consensus for a draconian docs policy.  Nor
>does "encouragement" work well; programmers, with much justification,
>feel that their code contributions deserve weight and that they are
>already contributing sufficiently to documentation.
>
Now that's just sad.
-- 

David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: "Extreme Documentation" [was: INFO on add-ons]

[Thien-Thi Nguyen]

   "Stephen J. Turnbull" <stephen@xemacs.org> writes:

   Aggregating that would
   be very useful, but how?

through indirection.  wikis point back to "official" as well as informal
documentation; if official maintainers do not sit on top of the tree, that's
ok, too.  to paraphrase godel on documentation: any collection that is
complete is not official and any official collection cannot be complete.

any policy (draconian or not) based on exclusion never leads to completeness.

you cannot exclude ignorance or other lackings, even if you tried.

thi

Re: "Extreme Documentation" [was: INFO on add-ons]

[Stephen J. Turnbull]

>>>>> "Thien-Thi" == Thien-Thi Nguyen <ttn@glug.org> writes:

    Thien-Thi>    "Stephen J. Turnbull" <stephen@xemacs.org> writes:
    Thien-Thi> Aggregating that would be very useful, but how?

    Thien-Thi> through indirection.

Not what I meant---that is implied by "wiki".  What I am concerned
about is that wikis grow organically according to the needs of their
current users.  This does not necessarily address the needs of someone
new coming in from outside the community, not as well as an
intelligent single author/editor can.

Also, wikis and FAQs address the past and the common use.  They do not
provide much if any support for innovative users and developers as
such---but once again, an intelligent author/editor could do wonders
with that material, I bet.

Finally, a pointer from the official documentation to the wiki is
useful, but users will justifiably consider that a "punt" by the
developers.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: "Extreme Documentation" [was: INFO on add-ons]

[Thien-Thi Nguyen]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

   Not what I meant---that is implied by "wiki".  What I am concerned
   about is that wikis grow organically according to the needs of their
   current users.  This does not necessarily address the needs of
   someone new coming in from outside the community, not as well as an
   intelligent single author/editor can.

it does address the newcomer needs if the newcomer takes a positive
attitude and contributes to the wiki.  the first contribution can
sometimes be simply a question that opens the eyes of others.  it is
easy to (none too subtly) dismiss emergent intelligence (especially if
you spend your days in an institute of policy and planning, which
presumably holds some kind of centralized (single root) model as tenet
:-).  that is an attachment that i can't help you with, however.

   Also, wikis and FAQs address the past and the common use.  They do
   not provide much if any support for innovative users and developers
   as such---but once again, an intelligent author/editor could do
   wonders with that material, I bet.

we have the internet and public publishing.  that's all that's needed
for you (or anyone innovative) to write a "blue sky" page, and seed it
w/: M-x index-wiki, M-x wiki-crawl-bot, M-x wiki-comp-lit-review, M-x
wiki-self-IQ-test, etc.  true innovation does not need as much hand-
holding as you would suggest; it might even suffer from it.

   Finally, a pointer from the official documentation to the wiki is
   useful, but users will justifiably consider that a "punt" by the
   developers.

exactly!  this is how users and developers work together.  so much nicer
than harping on some poor fool w/ write privs is to be foolish and free
amongst all your friends (some of whom enjoy/abuse write privs ;-).  if
some people practice excellence and demonstrate intelligence, hey that's
a bonus.  i'm glad to see that happening, anywhere.

thi

Re: INFO on add-ons

[Richard Stallman]

I believe GNU has its own install-info program which was written
initially by me.

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "rms" == Richard Stallman <rms@gnu.org> writes:

    rms> I believe GNU has its own install-info program which was
    rms> written initially by me.

I first encountered install-info around 1996 (the man page is dated
1994) as a Perl script written by Ian Jackson, as I wrote earlier.  On
several occasions I have built texinfo from scratch, which invariably
broke dpkg, so I had to move the GNU version of install-info out of
the way.  A quick look at the Info page for GNU install-info and the
man page for Debian install-info suggests they have further diverged.
:-(

Usually Debian is very careful to respect the upstream sources and
practices, so I jumped to the conclusion that GNU recognized a good
thing when it saw it, and decided to provide the same capability to
all Info users and admins.

I'm sorry if I provided misinformation about the origin of the utility.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Robert J. Chassell]

   >>>>> "rms" == Richard Stallman <rms@gnu.org> writes:

       rms> I believe GNU has its own install-info program which was
       rms> written initially by me.

   I first encountered install-info around 1996 (the man page is dated
   1994) as a Perl script written by Ian Jackson, as I wrote earlier.  ...

I do not know who wrote install-info first.  However, two different
programs of the same name were written.  Each solved the problem, but
worked differently.... :-(

In the past, I had some problems when I both built my own programs
from scratch and used Debian programs.  The conflicts meant that I
could not install Debian programs.  I have not had such problems in
the past couple of years.   :-)

Either the two programs now work together or one has been dropped or I
have not excited the conflict.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Henrik Enberg]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> I do not know who wrote install-info first.  However, two different
> programs of the same name were written.  Each solved the problem, but
> worked differently.... :-(
>
> In the past, I had some problems when I both built my own programs
> from scratch and used Debian programs.  The conflicts meant that I
> could not install Debian programs.  I have not had such problems in
> the past couple of years.   :-)
>
> Either the two programs now work together or one has been dropped or I
> have not excited the conflict.

There has been a big thread about this on the Debian lists in the last
couple of days.  As far as I can tell, the Debian developers have
decided to drop their install-info in favour of the GNU version.

-- 
Booting... /vmemacs.el

Re: INFO on add-ons

[Miles Bader]

On Tue, Sep 03, 2002 at 07:33:35PM +0200, Henrik Enberg wrote:
> There has been a big thread about this on the Debian lists in the last
> couple of days.  As far as I can tell, the Debian developers have
> decided to drop their install-info in favour of the GNU version.

I hope so, though I'd be happy if they'd just try to remain compatible.

[When I've reported missing features in debian's install-info as bugs (e.g a
new option added by GNU install-info), the replies I've gotten have been sort
of petulant (`we were first, they have to remain compatible with US!').]

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: INFO on add-ons

[Kai Großjohann]

Miles Bader <miles@gnu.org> writes:

> [When I've reported missing features in debian's install-info as bugs (e.g a
> new option added by GNU install-info), the replies I've gotten have been sort
> of petulant (`we were first, they have to remain compatible with US!').]

I got the same reaction.

kai
-- 
A large number of young women don't trust men with beards.  (BFBS Radio)

Re: INFO on add-ons

[Kai Großjohann]

Henrik Enberg <henrik@enberg.org> writes:

> There has been a big thread about this on the Debian lists in the last
> couple of days.  As far as I can tell, the Debian developers have
> decided to drop their install-info in favour of the GNU version.

Really?  They changed their mind?  Amazing.  But it's a good decision.

kai
-- 
A large number of young women don't trust men with beards.  (BFBS Radio)

Re: INFO on add-ons

[David A. Cobb]

Stephen J. Turnbull wrote:

>>>>>>"Miles" == Miles Bader <miles@lsi.nec.co.jp> writes:
>>>>>>            
>>>>>>
>    Miles> How so?  It seem to work well enough if people consistently
>    Miles> use `install-info' (and that actually seems to happen on
>    Miles> debian at least).
>
>I have no control over "people", and little enough over XEmacs.
>Better to spend the effort on having Emacs be smart about the info
>files themselves, which either it can read or it doesn't matter, than
>to have GNU and XEmacs.ORG try be anal about stuff that's not under
>our control.  IMO.
>
I don't see /any/ Free/Open Software project in a position to be anal 
about things.  I have no concept of anyone coercing a contributer in any 
regard - it'll cost you at least $30.00/hr to coerce /me/.

But it would be a considerable good if they did contribute Info pages 
and if installing the software also installed the info.  My notion was 
more an encouraging word in the documents we publish to guide the 
potential contributer.

>    Miles> People certainly have write access to the `dir' file in any
>    Miles> directory they write info files to.  Since info merges all
>    Miles> the different `dir' files into the final buffer at
>    Miles> run-time, that's all that's needed.
>
>That's fine, but I got the impression David was talking about the
>specific dir file in the info directory where Emacs stuff resides.
>
I dunno specifically /where/!  What I would hope for would be when I 
download, say, DoxyMacs from SourceForge I get a tar archive that 
includes the Info pages.  As for automatic installation, that shows my 
current Windoze milieu.  I think a script to take the bugs out of 
installing is a positive good thing.  If you do "$ configure  ...; make" 
then "Info" should be among the targets and should wind up doing "$ 
install-info" during "$ make install"
Windoze users should, IMNSHO, get a shell / cmd.exe script if not 
something like the Cygwin netinstaller because they are accustomed to 
one-step installation.
-- 

David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "David" == David A Cobb <superbiskit@cox.net> writes:

    David> I have no concept of anyone coercing a contributer in any
    David> regard - it'll cost you at least $30.00/hr to coerce /me/.

Oh, I think requiring revision of a patch because it has sucky
docstrings is both reasonable and coercive, and I doubt you would send
me a bill.  More like, "good grief, how could _I_ forget that!"  :-)

    David> But it would be a considerable good if they did contribute
    David> Info pages

Sure.  But we can't require Info pages, especially as rms has
pronounced against it.  Note that GNU is much more strict about
requiring docs when they are judged necessary than XEmacs.

    David> and if installing the software also installed the info.

It does:

bash$ fgrep .info /usr/lib/xemacs/xemacs-packages/pkginfo/MANIFEST.* | wc
    165     165   13072
bash$ fgrep -l info /usr/lib/xemacs/xemacs-packages/pkginfo/MANIFEST.* | wc
     42      42    2602
165 .info files in 42 (of 94) packages (and that omits Mule packages
and the core).  Yes, it's a shame that Swiss cheese has holes, but the
part that isn't holes is pretty tasty, no?

None of this is to deny that your perception of some problem is
unjustified.  But it's not obvious to me that either XEmacs or the
upstream maintainers are falling down on the job here.

    David> My notion was more an encouraging word in the documents we
    David> publish to guide the potential contributer.

There are plenty of those.  See standards.info, for example.  We could
probably strengthen them.  However, getting contributors to read those
is like getting users to read NEWS or the FAQ.

It's much more effective, and generally not taken too badly, for
reviewers to use moral suasion and the occasional veto.

    David> I think a script to take the bugs out of installing is a
    David> positive good thing.

Given your explanation of the points I didn't understand, I think (for
XEmacs usage) everything you want is satisfied by (1) writing more
Texinfo docs and (2) making more XEmacs packages.  We already do all
the installation and set up that you want.  If there are instances
where either the core code or an XEmacs package fails to install
existing docs, that is a bug and I would appreciate a report.

For (1), see my other post on "Extreme Documentation."

The main place that (2) falls down is that XEmacs packages don't much
care if their installation is useful to GNU Emacs or standalone Info
readers.  But setting INFOPATH=/path/to/xemacs-packages/info:$INFOPATH
should do the trick (modulo our interpretation of dir as a cache
rather than something that should be authoritative).


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[David A. Cobb]

Stephen J. Turnbull wrote:

>>>>>>"David" == David A Cobb <superbiskit@cox.net> writes:
>>>>>>            
>>>>>>
>
>    David> I have no concept of anyone coercing a contributer in any
>    David> regard - it'll cost you at least $30.00/hr to coerce /me/.
>
>Oh, I think requiring revision of a patch because it has sucky
>docstrings is both reasonable and coercive, and I doubt you would send
>me a bill.  More like, "good grief, how could _I_ forget that!"  :-)
>
Yes, indeed!

>    David> But it would be a considerable good if they did contribute
>    David> Info pages
>
>Sure.  But we can't require Info pages, especially as rms has
>pronounced against it.  
>
Ugh!  What's the 'in' thing now?  Didn't the GNU project /invent/ Info?  

>Yes, it's a shame that Swiss cheese has holes, but the
>part that isn't holes is pretty tasty, no?
>
Tasty, yes!

>But setting INFOPATH=/path/to/xemacs-packages/info:$INFOPATH
>should do the trick (modulo our interpretation of dir as a cache
>rather than something that should be authoritative).
>
Ah, I had it but had it wrong!   I had noticed that Xemacs/info-mode 
rebuilds the directory when I didn't expect it.

-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: INFO on add-ons

[Robert J. Chassell]

    >Sure.  But we can't require Info pages, especially as rms has
    >pronounced against it.  
    >
    Ugh!  What's the 'in' thing now?  Didn't the GNU project /invent/ Info?  

The GNU Project centered on Texinfo, which is a markup language that
enables you to generate from a single source file, output files for:

    Info        for efficient online help

    DVI         (or PostScript or PDF or ...)  for nicely typeset, hard
                copy printing

    HTML        for Web pages

    DocBook     for DocBook

    Plain text  for those who want that.

Please, do not write an Info file; write a Texinfo file instead.

The Texinfo file can be converted to Info, as well as to a form that
can be printed, to another that can be put on a Web site, and so on.
This is much better.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[David A. Cobb]

Robert J. Chassell wrote:

>    >Sure.  But we can't require Info pages, especially as rms has
>    >pronounced against it.  
>    >
>    Ugh!  What's the 'in' thing now?  Didn't the GNU project /invent/ Info?  
>
>The GNU Project centered on Texinfo, which is a markup language that
>enables you to generate from a single source file, output files for:
>
>    Info        for efficient online help
>
>    DVI         (or PostScript or PDF or ...)  for nicely typeset, hard
>                copy printing
>
>    HTML        for Web pages
>
>    DocBook     for DocBook
>
>    Plain text  for those who want that.
>
>Please, do not write an Info file; write a Texinfo file instead.
>
Yeah, I pretty much knew that.  But I think you're talking about the 
difference between what an author writes and what we distribute.  I 
agree, the contribtor guides should explicitly show how to build the 
documentation, what templates, etc. [like @copying]  So, yes, I was 
unclear.  Small parity error in cerebrum.
-- 

David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: INFO on add-ons

[Miles Bader]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
>     Ugh!  What's the 'in' thing now?  Didn't the GNU project /invent/ Info?  
> 
> The GNU Project centered on Texinfo, which is a markup language that
> enables you to generate from a single source file, output files for:

I think this is a terminology problem; most of the time when someone
says `write an info file', they really _mean_ `write a texinfo file'.
Because info files are never written in any other way, people often
seem to treat the terms as interchangeable.

I know that originally (in the days of the original emacs) there
actually were info files, but texinfo hadn't been invented yet; how did
people write info files then (by hand?!)?

-Miles
-- 
I have seen the enemy, and he is us.  -- Pogo

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Miles" == Miles Bader <miles@lsi.nec.co.jp> writes:

    Miles> I know that originally (in the days of the original emacs)
    Miles> there actually were info files, but texinfo hadn't been
    Miles> invented yet; how did people write info files then (by
    Miles> hand?!)?

Been there, done that.  Texinfo is not an improvement, if restricted
to generating Info files.  (Obviously the retargetable backend is a
_huge_ improvement, and I wouldn't go back, although I'd like to go
forward from Texinfo to XMLinfo.)


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Miles Bader]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
>     Miles> I know that originally (in the days of the original emacs)
>     Miles> there actually were info files, but texinfo hadn't been
>     Miles> invented yet; how did people write info files then (by
>     Miles> hand?!)?
> 
> Been there, done that.  Texinfo is not an improvement, if restricted
> to generating Info files.

Not an improvement over what?  Writing info files by hand?  It seems an
enormous improvement over that.

> I wouldn't go back, although I'd like to go forward from Texinfo to
> XMLinfo.

Why?  SGML and XML are quite unreadable compared to texinfo.

-Miles
-- 
Would you like fries with that?

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Miles" == Miles Bader <miles@lsi.nec.co.jp> writes:

    Miles> [Texinfo is n]ot an improvement over what?  Writing info
    Miles> files by hand?  It seems an enormous improvement over that.

Who wrote them by hand?  There was a mode, of course, probably still
is, buried in the info handling code somewhere.  It was close to
WYSIWYG, and given the limited expressiveness of TTYs, only a few
easily remembered "markup" forms.

    >> I wouldn't go back, although I'd like to go forward from
    >> Texinfo to XMLinfo.

    Miles> Why?  SGML and XML are quite unreadable compared to
    Miles> texinfo.

In a buzzword, Document Object Model.  I don't read texinfo, I read
Info.  And I don't want to write or edit texinfo, I want to move
hierarchical objects around (I'm mostly a manager, not a programmer;
ie, with docs, I edit and compile, not write). 

    Miles> Would you like fries with that?

No, I'll have onion rings.  ;)



-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Karl Eichwalder]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>     Miles> Why?  SGML and XML are quite unreadable compared to
>     Miles> texinfo.

This depends on the editor or viewer you are using.  I'm told the new
GNOME help system is designed to work with raw SGML (XML) files.

> In a buzzword, Document Object Model.  I don't read texinfo, I read
> Info.  And I don't want to write or edit texinfo, I want to move
> hierarchical objects around (I'm mostly a manager, not a programmer;
> ie, with docs, I edit and compile, not write). 

That's a good point.

Often, Texinfo commands are terse and thus obscure (I always have to
lookup how the reference commands are considered to work).  Don't take
me wrong---for some of my projects I prefer Texinfo, but in general I
hesitate to recommend the format to other writers.

Note, SGML offers features designed for readability: often it's possible
to omit end "tags" or minimize "tags":

    <em>foo</em> == <em/foo/

Not too mention the shortref/usemap feature which enables you to define
soemthing like:

    <p> == "\n\n"

    </row> == "|" or "\n"

And thus it's possible to write terse (and obsure) tables; in general
this feature is considerd harmful ;)

[I still believe HTML 2 is readable...]

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.suse.de/~ke/                                  |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: INFO on add-ons

[Robert J. Chassell]

       Miles> ... how did people write info files then (by hand?!)?

"Stephen J. Turnbull" <stephen@xemacs.org> responded:

   Been there, done that.  Texinfo is not an improvement, if restricted
   to generating Info files.  (Obviously the retargetable backend is a
   _huge_ improvement, and I wouldn't go back, ...

and then said:

    .... although I'd like to go forward from Texinfo to XMLinfo.)

Please write a short, introductory document explaining how to convert
a document written with XML markup to good, readable Texinfo
automatically, so it can then be converted to DVI (and Postscript,
PDF, etc), to HTML, to Info, and back again to DocBook and XML.

Also, please explain how to output a document written in an XML format
to Info and to the various other output formats. 

This is important.

Pretty obviously, many people are writing documentation in some form
or other of XML.  The best can be converted to Texinfo.  Some XML
formats require high resolution interfaces for people using their
eyes; these formats are poor for documentation.

Note that one of the major goals of Texinfo is to inspire and
constrain people to write documentation that is readable when typeset
and printed, when using a slow connection, or when working eyes-free
(as with driving a car or being permanently blind).  (That is to say,
`readable' means `listen-able using Emacspeak to convert text to
speech'.)

More than a decade ago, we considered switching from Texinfo to LaTeX
as the base markup language.  However, I found that people tended to
use LaTeX as a markup language for high-resolution typesetting and it
could not be used in all the output formats that Texinfo supports.

A great XML documentation format has to be constrained in the same way
as Texinfo -- this means that the best test for a great XML
documentation format is that it converts to good, readable Texinfo
automatically.

(I keep saying `good, readable Texinfo' because I have been told that
sometimes, XML sources are harder to read than Texinfo sources;
obviously, if this is true, we want to make sure that Texinfo keeps
its good qualities; and in any case, the converter should do a good
job.)

I am primarily a Texinfo person; I know little about the procedures
for converting one or other XML format to Texinfo (although I have
done it , to be sure it can be done).  I can never remember quite how
to describe how XML works.  (I.e., XML itself is not a mark up
language, but is a set of rules for creating different ones.  What
determines the mark up language itself, and how do you employ that?)

I cannot remember how to determine whether an XML source can be
converted to at least as many different output formats as Texinfo, nor
how to do that.  I cannot remember how to convert an XML source to
Texinfo.

I do remember how to convert Texinfo to DocBook and XML -- I put the
commands in the front of documents I write, so it is easy for me to
check my work by copying the commands and executing them in a shell.
For example:

    ## DocBook output
    makeinfo --docbook --no-split --paragraph-indent=0 \
    --verbose Rights-duty-metaphor.texi

    ## XML output
    makeinfo --xml --no-split --paragraph-indent=0 \
    --verbose Rights-duty-metaphor.texi

Please tell me how to create a file for printing, how to 
convert to Info, and how to convert to HTML these DocBook and XML
outputs that makeinfo creates.  

Also, more generally, please tell me about and what to do with XML:
how to convert to Texinfo, how to convert to the various output
formats, how to determine if the XML format is any good for
documentation and what the good ones are, where to get them for
sources, and how to install them from Debian.

And when you write, please presume that at least one of your readers
(me) is very tired, does not have much time, is situationally (or
maybe natively) stupid ....  and will have to come back to what you
wrote to determine yet again how to do the simplest thing.

Thank you.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Ville Skyttä]

On Wed, 2002-09-04 at 17:38, Robert J. Chassell wrote:

> Please write a short, introductory document explaining how to convert
> a document written with XML markup to good, readable Texinfo
> automatically, so it can then be converted to DVI (and Postscript,
> PDF, etc), to HTML, to Info, and back again to DocBook and XML.

No, this is not one, but:

> Also, please explain how to output a document written in an XML format
> to Info and to the various other output formats.

XSLT can do quite a lot.

And maybe docbook2X is worth something (don't know, I haven't tried it
out, nor do I know texinfo that well).  See
<http://docbook2x.sourceforge.net/>.

-- 
\/ille Skyttä
ville.skytta at xemacs.org

Re: INFO on add-ons

[Robert J. Chassell]

   On Wed, 2002-09-04 at 17:38, Robert J. Chassell wrote:

   > Please write a short, introductory document explaining how to convert
   > a document written with XML markup to good, readable Texinfo
   > automatically, so it can then be converted to DVI (and Postscript,
   > PDF, etc), to HTML, to Info, and back again to DocBook and XML.

ville.skytta@xemacs.org wrote:

   No, this is not one, but:
   .... 
   XSLT can do quite a lot.

   And maybe docbook2X is worth something....

Both are worth something.  I can assure you.  I have worked with both.
The problem is, I would have to reteach myself to do that again.  It
would take more time than I have.  What I need -- and many people are
in the same boat as me -- is a well written, short document that tells
me what to do (as well as why, so I remember).

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Robert" == Robert J Chassell <bob@rattlesnake.com> writes:

    Robert> Please write a short, introductory document explaining how
    Robert> to convert a document written with XML markup to good,
    Robert> readable Texinfo automatically,

It wouldn't be hard to write such a backend.  But we must agree on a
DTD first.

    Robert> A great XML documentation format has to be constrained in
    Robert> the same way as Texinfo

I would probably investigate a restriction of the DocbookXML DTD to
something isomorphic to Texinfo.

However, I would also want other constraints, constraints that would
make docstring-to-XML/Info conversion easy, and possibly additional
structure that would make it easier to create a structure editor that
moves nodes around.  In particular, nodes would be textually nested in
the markup, rather than implicitly via linking commands such as @menu
and the optional arguments of @node.

I also would like the various link formats (*ref, url, htmlurl) to be
unified in a single element that permits all of them simultaneously.
Designing this will take a fair amount of thought, though.  Eg, if
you're currently using an Info browser, you probably like Info.  So
first the browser tries to follow an Info link; if that fails, an HTML
URL, etc.

    Robert> Also, please explain how to output a document written in
    Robert> an XML format to Info

I don't currently know how to do that, because there is not yet a
suitable DTD.

    Robert> I keep saying `good, readable Texinfo' because I have been
    Robert> told that sometimes, XML sources are harder to read than
    Robert> Texinfo sources;

It shouldn't be hard to fix this.  It would be fairly easy to add a
feature to PSGML (if it isn't there already) to suppress uninteresting
attributes and tags, making _any_ XML more readable in PSGML.  More
important, the restricted Docbook (or whatever) would _have_ to have
fewer "uninteresting" attributes and tags, as they are generally
presentation features which should be excluded from the XML/Info DTD.

    Robert> I can never remember quite how to describe how XML works.

Here's your blurb.  Material in square brackets is rationale that
wouldn't actually appear in the blurb.  Comments welcome.

WHAT IS XML?

An XML processor reads several sets of rules.  The ruleset called the
"DTD" is concerned with the structure of a document.  Basically, XML
says "a document is a single sexp with colored parentheses," and the
DTD describes what colors are permitted, and the nesting rules among
colors.  The ruleset called the "style sheet" is concerned with
presentation of elements, such as logical faces like "emphasis,"
indentation, link coloring or underlining, and so on.

DTDs are written in a language defined by the SGML standard.  Style
sheets have a couple of alternative languages, such as the cascading
style sheet (CSS) specification and XML schemas.  Many processors
support both.  In general, to use XML/Info you will rarely need to
read, much less write, DTDs or style sheets.  But it may be comforting
to know a little about the structure of the process.  And it's
possible that you'll want to read the DTD to understand why the PSGML
mode or the XML processor doesn't like your documents, or the style
sheet to understand the formatting you see on output.

The presentation itself might be quite abstract.  For example, it
would be straightforward to create an XMLlikeTeXInfo DTD that simply
implements Texinfo @ macros as XML elements of the same name.  The
style sheet would simply be the inverse mapping back to Texinfo.  [For
a number of reasons, I would prefer to derive an XMLInfo DTD from
something like DocbookXML, but that's not the users' problem.]

Once set up in this way, you feed the document to the XML processor,
optionally specifying a target format (such as PDF, XHTML, or even
Texinfo as in the example of the preceding paragraph).  Then you
publish the output in the ways usual for the target format.

HOW DO I USE XML/Info?

In order to create an XML Info document source, you first put an XML
declaration at the top of the file, followed by a document type
declaration.  For normal use, these are boilerplate (which would be
automatically inserted by an xmlinfo-mode derived from PSGML).  Then
you use a structure-based editor such as PSGML, along with the style
rules in the Creating a Texinfo File node of Info (suitably translated
to treat XML rather than Texinfo markup) to edit the text and markup.

Finally, you run the XML processor on the document.  There are any
number of XML processors which are suitable for implementing this
process.  [to be filled in with names and URLs, and sample commands]
Most allow you to specify the target.  XML/Info also provides
xml2texi.el, a mode for converting a buffer from XML/Info to Texinfo,
for those who prefer that format for proofreading.  [Hypothetically it
does ;]  xmlinfo-mode would also probably provide C-c C-c bindings for
commands to run the XML processor and produce output.


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Robert J. Chassell]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

    However, I would also want other constraints, ...  In particular,
    nodes would be textually nested in the markup, rather than
    implicitly via linking commands such as @menu and the optional
    arguments of @node.

I am not sure exactly what you mean.  Would an enhancement of
`texinfo-show-structure' to enable an outline minor mode or folding
do what you want?

For example, you can run a Texinfo outline mode using this regexp:

(setq outline-regexp
      (concat
       "@major\\|"
       "@chapte\\|"
       "@chaphe\\|"
       "@unnumb\\|"
       "@append\\|"
       "@section\\|"
       "@unnumbe\\|"
       "@appendi\\|"
       "@appendi\\|"
       "@heading\\|"
       "@subsecti\\|"
       "@unnumber\\|"
       "@appendix\\|"
       "@subheadi\\|"
       "@subsubsect\\|"
       "@unnumbered\\|"
       "@appendixsu\\|"
       "@subsubhead"))

but the end of a segment is the beginning of the next heading, so the
node and comment lines that preceed the next heading line are included
in the previous segment.

Currently you can run `texinfo-show-structure', but it does not work
well with Outline mode.  Would a combination do the job for you?

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Robert" == Robert J Chassell <bob@rattlesnake.com> writes:

    Robert> Currently you can run `texinfo-show-structure', but it
    Robert> does not work well with Outline mode.  Would a combination
    Robert> do the job for you?

No.  First, I want to use third-party tools.  XML tools are growing
like a bamboo garden.  Texinfo is at best a mature bonsai by
comparison.  Second, AFAICT texinfo doesn't care about the textual
structure of a texi document.

@node a, b, , top
@menu
* c
* d
@end menu
@node c, d, , a
@node d, , c, a
@node b, , a, top

and

@node a, b, , top
@menu
* c
* d
@end menu
@node b, , a, top        <-- Node b jumps 2 places to Number Two on
                             the Billboard Node Charts!  Number Two,
                             Two, Two....
@node c, d, , a
@node d, , c, a

are identical structures from the point of view of Texinfo.  This
means that the processor must know the semantics of the name, next,
previous, and up attributes of a node to deduce what any XML processor
"just knows".

That means that every function I use must contain special code that
knows about @node.  Of course this is do-able, but why spend the
effort when every DOM processor already knows how to manipulate these
hierarchical structures?  Furthermore, in general the structure of SAX
parsers will give you the same result implicitly.  (An actual
structure editor would want DOM, of course.)

Once again, not everybody needs this.  I'm just explaining why I want
this, and I don't know whether it would be worth converting to XML
globally for Emacs or GNU.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Robert J. Chassell]

"Stephen J. Turnbull" <stephen@xemacs.org> writes

    .... AFAICT texinfo doesn't care about the textual structure of a texi document.

I think I understand what you mean.  In Texinfo, a node structure may
be any directed graph, not just a hierarchical one.

This is intended to be a feature:  you and arrange your node structure
as you wish.

It is true that most documents are written like a book with a
hierarchical structure, but they don't need to be. (However, the
various help tools, like `texinfo-all-menus-update' that I wrote all
require that the document follow a hierarchical structure since I
lacked the ability or time to do otherwise.)


As I see it, for documentation, the main problem with XML is exactly
the same as the problem with LaTeX or HTML:  most writers want to
write for a single output format, and they pick one that does not
convert readily to other output formats.

Consequently, they write documents that do poorly when you are
connected over a slow line (as still happens to me at intervals), or
when you must work eyes-free (as when driving a car, or permanently
blind).

So my question to you is:  does the present Texinfo --> XML converter
produce XML that works with the tools you need?  And is there a good
XML --> Texinfo to convert the result back to Texinfo?

If so, then we would benefit from tools in Emacs that make the
conversions automatically from one to the other, that check whether
usability constraints are met by running Texinfo, that check whether
other constraints are met or that auto-generate documentation, by
running XML tools.

(Incidentally, to answer Miles' question, yes, the XML --> Texinfo
must produce `good, readable' Texinfo, since the presumption is that
other people, in addition to the author, will modify it.  Since the
Texinfo is the canonical form, it should not be `placed in a swamp'
that is hard to study or modify, like binary-only programs.)

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Miles Bader]

On Fri, Sep 06, 2002 at 12:18:28PM +0000, Robert J. Chassell wrote:
> (Incidentally, to answer Miles' question, yes, the XML --> Texinfo
> must produce `good, readable' Texinfo, since the presumption is that
> other people, in addition to the author, will modify it.  Since the
> Texinfo is the canonical form, it should not be `placed in a swamp'
> that is hard to study or modify, like binary-only programs.)

I was talking about cases where XML was used as the `source form' (presuming
that the author of some package preferred to write his document in that
form).

In such a case it would be very bad to modify the generated texinfo, and I
see little benefit in `studying' it (since anyone familiar with texinfo can
probably look at the XML source and figure out what's going on with little
trouble).

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: INFO on add-ons

[Richard Stallman]

Could people please take this Texinfo vs XML discussion away from
emacs-devel?

Re: INFO on add-ons

[Robert J. Chassell]

"Stephen J. Turnbull" <stephen@xemacs.org> provided a nice blurb about
XML.  That is a beginning.  I have saved it.    Thank you!

Now, more questions:

I have two documents.  One has the heading: 

    <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

and the other has the heading:

    <!DOCTYPE texinfo SYSTEM "texinfo.dtd">

(I just created these files with the shell commands:

   makeinfo --docbook --no-split --paragraph-indent=0 --verbose foo.texi
   makeinfo --xml --no-split --paragraph-indent=0 --verbose foo.texi

The file were created without reported error, and I presume they
actually fit the DocBook V3.1 and texinfo DTDs.  I do know that the
foo.texi Texinfo source produces good Info and DVI files, since I have
looked at them.)

What do I do to convert these XML files to Info, HTML, and to DVI or
other typesetting markup?

My questions are specific; pretend (well, no need to pretend... :)
that I don't know anything:

  - what files do I download and install?

  - (Ideally, what are the appropriate Debian /etc/apt/sources.list lines and the
    apt-get commands?)

  - what commands do I run to create the output files?

In other words, what is the currently existing XML processor I should
use, where do I get it, and what are the specific commands I should
give it?

Thanks.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Ville Skyttä]

On Thu, 2002-09-05 at 16:54, Robert J. Chassell wrote:

> In other words, what is the currently existing XML processor I should
> use, where do I get it, and what are the specific commands I should
> give it?

One point to start from could be libxml [1] and libxslt [2].  You might
also want to grab the DocBook XSL's from [3], also take a look at the
XSL documentation in [3], the examples in particular.  After
installation, "man xsltproc" will tell you more.

Since you said you're running Debian,

   apt-get install docbook-xsl libxml2 libxslt1

...could do the installation for you (not verified, you might need to
change libxml2 to libxml1).  There's a bunch of stuff that looks
interesting if you search for "docbook" at
<http://www.debian.org/distrib/packages#search_packages>.

[1] <http://xmlsoft.org/>
[2] <http://xmlsoft.org/XSLT/>
[3] <http://docbook.sourceforge.net/projects/xsl/>

HTH,
-- 
\/ille Skyttä
ville.skytta at xemacs.org

Re: INFO on add-ons

[Stefan Monnier]

>     Miles> I know that originally (in the days of the original emacs)
>     Miles> there actually were info files, but texinfo hadn't been
>     Miles> invented yet; how did people write info files then (by
>     Miles> hand?!)?
> 
> Been there, done that.  Texinfo is not an improvement, if restricted
> to generating Info files.

Huh?!?  What kind of wacky Emacs macros did you have to maintain indices
and to ensure a consistent style when editing Info files ?

> (Obviously the retargetable backend is a
> _huge_ improvement, and I wouldn't go back, although I'd like to go
> forward from Texinfo to XMLinfo.)

What's so great about <kindex key="C-x k"/> compared to @kindex C-x k ?
What's so great about <sample>foobar</sample> compared to @sample{foobar} ?
XML has its advantages, but for a *source* format, it's just way too
cumbersome/verbose, unless you use an editor that hides the markup,
but then what would such an editor look like ?
If you say WYSIWYG, you know that it is very difficult to reconcile
with the purpose of TeXinfo which is to concentrate on the intent
and allow many *different* output formats.


	Stefan

Re: INFO on add-ons

[Robert J. Chassell]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

    If you say WYSIWYG, you know that it is very difficult to
    reconcile with the purpose of TeXinfo which is to concentrate on
    the intent and allow many *different* output formats.

Yes.  One way to think about this is that the Texinfo source provides
the `deep structure' of a document, while the various output formats
provide `surface representations'.

A while back, I wrote a little package, very brittle, that
showed three of the output formats you could produce from a Texinfo
file that you are working on:  Info in GNU Emacs, HTML in a Web
browser, and DVI in an xdvi window.  

I ended up not caring for it; I am happy enough copying the necessary
shell commands to a xterm and generating the output that way.  But it
is an interesting idea.

Here is the code, if anyone wants to try it or improve on it.  As I
said this is brittle and has a hard time with errors.  Your Texinfo
source must format without reported error.



;;;; texinfo-split-screen.el
;;;; 2002 Jun  5
;;;; Robert J. Chassell, bob@gnu.org
;;;; low alpha quality at the moment.

;;;; Does NOT report errors well..... :-(

;; To use this, start GNU Emacs with two frames.  Load this file.
;; Find the Texinfo file on which you are working in one frame.
;; Invoke `M-x texinfo-split-screen' on that Texinfo file.

;; The dvi file and the Web browser file will appear, but at the
;; beginning of the document.  The Info file will appear in the other
;; window at the beginning of the node where you are located in the
;; Texinfo file.

;; At the moment, we need the 

;;       (sit-for 1)
;;       (message "current-nodename --> %s and info-place --> %s"
;;                current-nodename info-place)
;;       (sleep-for 3)

;; so that the `makeinfo --no-split --paragraph-indent=0 --verbose'
;; process has an opportunity to complete before Info is run on the
;; resulting .info file.  This should be changed so that Info is run
;; only after the `makeinfo' process completes.

;; The trouble with the following `add-hook' is that it runs
;; `texinfo-split-screen' after *every* save, not just after 
;; saves for the Texinfo file.... :-)       So it is no good.
;; (add-hook 'after-save-hook 'texinfo-split-screen)

(defun texinfo-split-screen ()
  "Update Info, HTML, and DVI outputs of current Texinfo buffer."
  (interactive)
  (widen)
  (let ((split-screen-current-buffer (buffer-name)))

    (set-buffer split-screen-current-buffer)
    (let ((current-process-list (process-list)))
      (while current-process-list
        (if (equal "texi2dvi"
                   (substring (process-name (car current-process-list)) 0 8))
            (kill-process (car current-process-list)))
        (setq current-process-list (cdr current-process-list))))

    ;; remove following files first:
    ;;     *.dvi *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr 

    (apply 'start-process
           ;; NAME for the process
           (concat "rm "
                   (file-name-sans-extension (buffer-file-name)) 
                   ".toc" " "
                   (file-name-sans-extension (buffer-file-name)) ".aux")
           nil                          ; BUFFER
           "rm"                         ; PROGRAM
           ;; ARGs to PROGRAM
           (list 
            (concat (file-name-sans-extension (buffer-file-name)) ".toc")
            (concat (file-name-sans-extension (buffer-file-name)) ".aux"))
           )

    (apply 'start-process
           (concat "texi2dvi " (buffer-file-name)) ; NAME for the process
           nil                          ; BUFFER
           "texi2dvi"                   ; PROGRAM
           (list (buffer-file-name))    ; ARGs to PROGRAM
           )

    (texinfo-split-screen-view-xdvi
     (concat (file-name-sans-extension (buffer-file-name)) ".dvi"))

    (set-buffer split-screen-current-buffer)
    (apply 'start-process
           ;; NAME for the process
           (concat "makeinfo --html --no-split --verbose " (buffer-file-name))
           nil                          ; BUFFER
           "makeinfo"                   ; PROGRAM
           ;; ARGs to PROGRAM
           (list "--html" "--no-split" "--verbose" (buffer-file-name)) 
           )

    (let ((current-process-list (process-list)))
      (while current-process-list
        (if (equal "galeon"
                   (substring (process-name (car (process-list))) 0 6))
            (kill-process (car current-process-list)))
        (setq current-process-list (cdr current-process-list))))

    (let ((browse-url-new-window-flag -1))
      (texinfo-split-screen-view-HTML
       (concat (file-name-sans-extension (buffer-file-name)) ".html")))

    (sit-for 1)

    (set-buffer split-screen-current-buffer)
    (let ((info-file-creation-process
           (apply 'start-process
                  (concat               ; NAME for the process
                   "makeinfo --no-split --paragraph-indent=0 --verbose "
                   (buffer-file-name))
                  nil                   ; BUFFER
                  "makeinfo"            ; PROGRAM
                  (list                 ; ARGs to PROGRAM
                   "--no-split" "--paragraph-indent=0" "--verbose"
                   (buffer-file-name)))))
      (setq info-file-creation-process-name
            (process-name info-file-creation-process)))

    (message "sit-for 5")
    (sit-for 5)

    (if (eq (process-status info-file-creation-process-name) nil)
        ;; start Info reader
        (progn
          (or (functionp 'texinfo-copy-node-name)
              (require 'texnfo-upd))
          (let* ((current-location (point))
                 (current-nodename
                  (if (re-search-backward "^@node" (point-min) t)
                      (texinfo-copy-node-name) "Top"))
                 (current-filename
                  (progn
                    (goto-char (point-min))
                    (search-forward "@setfilename ")
                    (expand-file-name
                     (buffer-substring
                      (point) (save-excursion (end-of-line) (point))))))
                 (info-place
                  (concat "(" current-filename ")" current-nodename)))
            (goto-char current-location)
            (sit-for 1)
            (message "current-nodename --> %s and info-place --> %s"
                     current-nodename info-place)
            (sleep-for 3)
            (texinfo-split-screen-info info-place))
          ))))

(defun texinfo-split-screen-view-xdvi (xdvifile)
  "Ask  xdvi to view a .dvi file."
  (interactive "fxdvi file: ")
  ;;  -sourceposition  line[:col][ ]filename
  (defvar xdvi-process-name "xdvi-process-holder")

  (if (eq (process-status xdvi-process-name) nil)
      ;; start xdvi
      (let ((process
             (apply 'start-process
                    (concat "xdvi " xdvifile) ; NAME for the process
                    nil                 ; BUFFER
                    "xdvi"              ; PROGRAM
                    (list xdvifile)     ; ARGs to PROGRAM
                    )))
        (setq xdvi-process-name (process-name process)))
    ;; else
    (continue-process xdvi-process-name)))

(defun texinfo-split-screen-view-HTML (htmlfile)
  "Ask Galeon to view an HTML file."
  (interactive "fHTML file: ")
  (defvar galeon-process-name "galeon-process-holder")

  (if (eq (process-status galeon-process-name) nil)
      ;; start galeon
      (let ((process
             (apply 'start-process
                    (concat "galeon " htmlfile) ; NAME for the process
                    nil                 ; BUFFER
                    "galeon"              ; PROGRAM
                    (list htmlfile)     ; ARGs to PROGRAM
                    )))
        (setq galeon-process-name (process-name process)))
    ;; else
    (continue-process galeon-process-name)))

(defun texinfo-split-screen-info (file)
  "For texinfo-split-screen, enter Info in another window."
  (if (buffer-live-p (get-buffer "*info*"))
      (kill-buffer (get-buffer "*info*")))
;;  (message " sleep 2 then go to other frame")
;;  (sleep-for 2)
  (other-frame 1)
  (get-buffer "*info*")
  (switch-to-buffer "*info*")
  (Info-goto-node file))

;;;;;;;;;;;;;;;; end texinfo-split-screen.el ;;;;;;;;;;;;;;;;

Re: INFO on add-ons

[Ville Skyttä]

On Wed, 2002-09-04 at 18:49, Stefan Monnier wrote:

> > (Obviously the retargetable backend is a
> > _huge_ improvement, and I wouldn't go back, although I'd like to go
> > forward from Texinfo to XMLinfo.)

Yeah!  Thumbs up here.

> What's so great about <kindex key="C-x k"/> compared to @kindex C-x k ?
> What's so great about <sample>foobar</sample> compared to @sample{foobar} ?

The user base.  What do you think is the percentage of the technically
oriented people, especially "newcomers", that feel more comfortable with
the former?  Why should a "newcomer" who has a choice learn Texinfo if
she already knows XML?  IMO this is an important accessibility question
too, not just syntactic sugar.

> XML has its advantages, but for a *source* format, it's just way too
> cumbersome/verbose, unless you use an editor that hides the markup,
> but then what would such an editor look like ?

I don't agree.  There's a lot of people who actually like the tag soup,
and who think that a decent syntax highlighting and indentation engine
is good enough.  But the point actually is that people have a choice to
work with XML the way they want.

Some free approaches (no, I haven't tried all of them out):
  <http://psgml.sourceforge.net/>
  <http://kxmleditor.sourceforge.net/>
  <http://idx-getox.idealx.org/>
  <http://www.aleksey.com/yaxed/>
  <http://www.freesoftware.fsf.org/mlview/>
  <http://www.alphaworks.ibm.com/tech/xeena>

Of course, there's also a lot of commercial implementations around.

> If you say WYSIWYG, you know that it is very difficult to reconcile
> with the purpose of TeXinfo which is to concentrate on the intent
> and allow many *different* output formats.

No, there's no such thing as WYSIWYG in XML.  It's about structure, not
presentation, as I gather Texinfo is too.  And as I already said in
another message, there's quite a lot one can do with XSLT.

I'm not saying that any project should change from Texinfo to XML
overnight, especially because I don't know enough about the former. 
Personally, I wouldn't mind that, but of course there's a lot of people
who would.  If there's a way to use both XML and Texinfo and make them
coexist happily, I'm all for it.

-- 
\/ille Skyttä
ville.skytta at xemacs.org

Re: INFO on add-ons

[Miles Bader]

Ville Skyttä <ville.skytta@xemacs.org> writes:
> > > (Obviously the retargetable backend is a _huge_ improvement, and I
> > > wouldn't go back, although I'd like to go forward from Texinfo to
> > > XMLinfo.)
> 
> Yeah!  Thumbs up here.

I think it depends on what's meant by `go forward'.

XML makes a decent intermediate format, but it's a pretty poor source
format.

If we had tools to do XML->info, XML->tex, etc., and a tools that did
texinfo->XML, then we could support both formats, and leave it up to
the original author of a document which he preferred to use.

This would end up making people unhappy I suppose (I'd be annoyed to
edit XML docs, and XML-structure-editor-users would be annoyed to work
on texinfo), but it might result in more documentation.

> > What's so great about <kindex key="C-x k"/> compared to @kindex C-x k ?
> > What's so great about <sample>foobar</sample> compared to @sample{foobar} ?
> 
> The user base.  What do you think is the percentage of the technically
> oriented people, especially "newcomers", that feel more comfortable with
> the former?  Why should a "newcomer" who has a choice learn Texinfo if
> she already knows XML?

I'd guess that the `user base' of XML falls into two camps:

  (1) Those who are afraid of any markup language, and would insist on
      using a structure editor or something.  These people don't `know
      XML'.

  (2) People who actually know XML.  These people will pick up
      texinfo's syntax in about 35 seconds (both syntaxes are really
      almost trivial).

It's group (1) that's really relevant to your argument, but my
impression is that almost all free-software documentation currently
comes from group (2).

The question is whether making things easier for group (1) would improve
the documentation situation significantly (it has to be `significantly'
of course, because otherwise it's not worth the effort).

I don't the answer to this.

> > XML has its advantages, but for a *source* format, it's just way too
> > cumbersome/verbose, unless you use an editor that hides the markup,
> > but then what would such an editor look like ?

[ like texinfo (`@tag{...}'), of course :-) ]

> If there's a way to use both XML and Texinfo and make them
> coexist happily, I'm all for it.

Indeed...

-Miles
-- 
We live, as we dream -- alone....

Re: INFO on add-ons

[Karl Eichwalder]

Miles Bader <miles@lsi.nec.co.jp> writes:

>   (2) People who actually know XML.  These people will pick up
>       texinfo's syntax in about 35 seconds (both syntaxes are really
>       almost trivial).

Texinfo is too terse.  Often it's ambiguous.  And its parsers
(makeinfo?)  are too graceful; there isn't any so called validator.
Okay, some of us might consider these issues as features ;)

Every project maintainer has to decide on his own whether he want to
make use of things SGML can offer.  For what's worth, SGML is an ISO
standard; XML is not, though.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.suse.de/~ke/                                  |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: INFO on add-ons

[Eli Zaretskii]

On Thu, 5 Sep 2002, Karl Eichwalder wrote:

> there isn't any so called validator.

What's wrong with Info-validate?

Re: INFO on add-ons

[Karl Eichwalder]

Eli Zaretskii <eliz@is.elta.co.il> writes:

> What's wrong with Info-validate?

Probably nothing per se.

Sometimes you want restrictions like: Don't use @strong or @subsection
is forbidden.

As I said: if Texinfo is good enough for your project use it; but don't
assume other projects require other features which are difficult to
mimick using Texinfo.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.suse.de/~ke/                                  |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: INFO on add-ons

[Robert J. Chassell]

   Texinfo is too terse.  

Please give examples of what you mean.  Perhaps they should go into
the documentation; or perhaps Texinfo should be changed.

    Often it's ambiguous.  

Again, please give an example.


   And its parsers (makeinfo?)  are too graceful; there isn't any so
   called validator.

I am puzzled by this:  I get good validation by running makeinfo to
produce 5 different output formats, and running texi2dvi to produce
another output format.  I just paste the appropriate shell commands
(which I keep near the beginning of my source file) into a shell.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Eli Zaretskii]

On 5 Sep 2002, Miles Bader wrote:

> > > What's so great about <kindex key="C-x k"/> compared to @kindex C-x k ?
> > > What's so great about <sample>foobar</sample> compared to @sample{foobar} ?
> > 
> > The user base.  What do you think is the percentage of the technically
> > oriented people, especially "newcomers", that feel more comfortable with
> > the former?  Why should a "newcomer" who has a choice learn Texinfo if
> > she already knows XML?
> 
> I'd guess that the `user base' of XML falls into two camps:
> 
>   (1) Those who are afraid of any markup language, and would insist on
>       using a structure editor or something.  These people don't `know
>       XML'.
> 
>   (2) People who actually know XML.  These people will pick up
>       texinfo's syntax in about 35 seconds (both syntaxes are really
>       almost trivial).

Yes.  In my experience (with reviewing docs written by others and 
teaching them basic Texinfo), picking up Texinfo markup is the least of 
your problems when writing documentation.  Especially since Emacs makes 
it so easy to produce the markup with simple key sequences.

Re: INFO on add-ons

[Stephen J. Turnbull]

>>>>> "Stefan" == Stefan Monnier <monnier+gnu/emacs@rum.cs.yale.edu> writes:

    Stefan> Huh?!?  What kind of wacky Emacs macros did you have to
    Stefan> maintain indices and to ensure a consistent style when
    Stefan> editing Info files ?

I didn't do indicies (at the time writing Info was a lot easier for me
than the mechanics of contributing, so I knew what was in there), mea
maxima culpa, although I doubt it would be that hard to write a macro
to do it.

As for style, Info has basically three forms of physical presentation,
*emphasis*, `literals' and META VARIABLES.  Very mnemonic.  (I find
modern Texinfo bewildering in its variety of useful-only-in-the-
hardcopy markup, @url and @htmlurl and @file and @dir and @subdir
and @lionsandtigersandbearsohmy and so on.)

    Stefan> What's so great about <kindex key="C-x k"/> compared to
    Stefan> @kindex C-x k ?

I wouldn't have a kindex element.  It would be an attribute of the key
element:

<key index="def" xindex="kill-buffer">C-x k</key> runs the command
<cmd index="ref">kill-buffer</cmd>. ... An alternative to
<key index="ref">C-x k</key> <key>RET C-x b UP RET</key> is
<key>M-x <cmd index="ref">erase-buffer</cmd> RET</key>.

This means that it would be easy to make an XML-based indexing helper.
If you just index all references, it could be automatic.  If you want
intelligent indexing, as above, it would be interactive.  This would
mean that it's hardly a crime to be lazy about indexing, as I was with
the third key element above.  I'm sure you could do it with regexps
and Lisp for texinfo, too, but with XML these possibilities just walk
up and bite you on the ankle.

Furthermore, XML allows you to take natural advantage of commonality,
as I did in the example above by endowing the cmd element with an
index attribute.  Now, any time I want to index something, I just add
an index attribute.  I don't need to remember @kindex and @cindex and
@whateverindexthetexinfomaintainerdeemsnecessarytoday.  If we add an
"eg" (to be distinguished from "ref") value for index attributes, then
it's easy to ensure all indexables share that new distinction.

And the validating parser will barf if index isn't an attribute of
key, while Texinfo doesn't care if I @kindex{Stefan Monnier}.  (Tell
me about how easy it would be to fix _that_ bug.)  If I really want to
index keys, I report it to the XML/Info maintainer as an RFE.  If
approved, implementation is trivial.  You change the definition in two
places in the DTD.  You add the index attribute to key, and key to the
list of indexables for an appropriate index.

It's also easy to add features like xindex, which would automatically
put "see also" entries in the indicies.

    Stefan> What's so great about <sample>foobar</sample> compared to
    Stefan> @sample{foobar} ?

Nothing.  Once again, I want the Document Object Model, so I can use
the many tools that are being developed for structure manipulation.  I
want locality (index an attribute of key, rather than a separate
markup).  I want orthogonality, so that once a new contributor learns
a concept, she can employ it correctly everywhere.  Documentation
should be do-able by users who aren't specialists in Emacs or in
documentation.  (See the Thi-Thien Nguyen thread.)

    Stefan> XML has its advantages, but for a *source* format, it's just
    Stefan> way too cumbersome/verbose,

That is clearly a deficiency of XML in this application, although I
hardly think it's crippling.  In "suppress-attribute" mode, the
example above appears as

<key>C-x k</key> runs the command <cmd>kill-buffer</cmd>. ... An
alternative to <key>C-x k</key> <key>RET C-x b UP RET</key> is
<key>M-x <cmd>erase-buffer</cmd> RET</key>.

Perhaps with fontification to indicate that some of the elements have
hidden attributes.  Still more verbose, but I'm willing to sacrifice
terseness for the power and orthogonality I've described above, power
that Somebody Else Somewhere is already implementing and maintaining
for me.  YMMV.

    Stefan> unless you use an editor that hides the markup, but then
    Stefan> what would such an editor look like ?

PSGML?  outline-mode (for structure editing)?  It would even be
possible to use TeX-like <elt>{element contents} notation to decrease
verbosity.

    Stefan> If you say WYSIWYG

Please, I have asthma.  Take your strawman outside.  ;-)


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py

Re: INFO on add-ons

[Richard Stallman]

We're not going to replace Texinfo with a different format,
so please don't spend a lot of time arguing about the question.

However, GNU packages are welcome to use any other format you like
which can be converted automatically into a good Texinfo file.  So
there's no need to argue about that either.

Re: INFO on add-ons

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> However, GNU packages are welcome to use any other format you like
> which can be converted automatically into a good Texinfo file.

Does `good' mean `readable', or just `parseable by makeinfo'?

The latter seems all that's necessary (since in that case no one should
make changes to the texinfo file, as it's not the true source).

-Miles
-- 
Saa, shall we dance?  (from a dance-class advertisement)

Re: INFO on add-ons

[Richard Stallman]

    > However, GNU packages are welcome to use any other format you like
    > which can be converted automatically into a good Texinfo file.

    Does `good' mean `readable', or just `parseable by makeinfo'?

It mostly means parseable by makeinfo and by TeX, but it should not
be too hard for humans to understand.

Re: INFO on add-ons

[Eli Zaretskii]

On 4 Sep 2002, Miles Bader wrote:

> I know that originally (in the days of the original emacs) there
> actually were info files, but texinfo hadn't been invented yet; how did
> people write info files then (by hand?!)?

Yes, AFAIK.

Re: INFO on add-ons

[Robert J. Chassell]

   I know that originally (in the days of the original emacs) there
   actually were info files, but texinfo hadn't been invented yet; how did
   people write info files then (by hand?!)?

Yes, by hand.  It took a great deal of effort to persuade people to
write Texinfo files.  

Just as there are still people who think primarily in hardcopy printed
material (and who use a ghastly markup language such as PDF), there
are others who think primarily in online help methods.  

The latter forget that online help should sometimes be read in hard
copy.  Similarly, the former forget that at times the contents of a
hard copy document should be read on line.

Many people have not yet come to understand that the change in
technology over the past half century has led to a change in how to
publish.  I suspect this is similar to the resistance to printing in
the half century after Gutenberg invented the use of moveable type.

-- 
    Robert J. Chassell            bob@rattlesnake.com  bob@gnu.org
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8

Re: INFO on add-ons

[Richard Stallman]

    I think this is a terminology problem; most of the time when someone
    says `write an info file', they really _mean_ `write a texinfo file'.
    Because info files are never written in any other way, people often
    seem to treat the terms as interchangeable.

Yes, that's right.  I don't think we should insist on a Texinfo file
or an Info file for every package in Emacs.  It's worth having one
for some packages, but many don't need one.

Re: INFO on add-ons

[David A. Cobb]

Stephen J. Turnbull wrote:

>>>>>>"David" == David A Cobb <superbiskit@cox.net> writes:
>>>>>>            
>>>>>>
>
>    David> Would nearly everyone agree that folks who provide/maintain
>    David> packages or FSF Emacs add-ons ought to consider it a
>    David> professional obligation
>
>_Obligation_?  Not.
>
/Professional/ obligation - to youself! before you say the job is done.

-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

Re: INFO on add-ons

[Richard Stallman]

    Would nearly everyone agree that folks who provide/maintain packages or 
    FSF Emacs

Please don't call our program "FSF Emacs".  That term was
coined by XEmacs developers and it is subtly a put-down.

I don't think all Emacs packages need their own manuals.
Only some of them need manuals.

Re: INFO on add-ons

[David A. Cobb]

Richard Stallman wrote:

>    Would nearly everyone agree that folks who provide/maintain packages or 
>    FSF Emacs
>
>Please don't call our program "FSF Emacs".  That term was
>coined by XEmacs developers and it is subtly a put-down.
>
Absolutely no put-down or negative conotation was intended.  To anyone 
whose toes feel bruised I sincerely apologise.

>
>I don't think all Emacs packages need their own manuals.
>Only some of them need manuals.
>
No, not manuals.  But 1 - 5 Info pages for the user would be nice.

And some things do deserve a full-up users' manual.

By now there is far, far more in (X)Emacs than /any/ user is likely to 
have on the top of her head.

>_______________________________________________
>Emacs-devel mailing list
>Emacs-devel@gnu.org
>http://mail.gnu.org/mailman/listinfo/emacs-devel
>
>  
>

-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.

INFO on add-ons

[David A. Cobb]

Would nearly everyone agree that folks who provide/maintain packages or 
FSF Emacs add-ons ought to consider it a professional obligation to 
provide an Info source covering their software, and that any 
installation process ought to support this by merging these 
(INSTALL-INFO)  with the Emacs Info.Dir?

Just a thought!

-- 
David A. Cobb, Software Engineer, Public Access Advocate
"By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr.
Life is too short to tolerate crappy software.
.