On being web-friendly and why info must die

On being web-friendly and why info must die

[Eric S. Raymond]

Several recent posts in the metaproblem threads have had the common
theme that Emacs's web resources are weak, scattered, and unfocused.
In particular, guidance for new developers that should be public,
prominent and webbed is buried in obscure text files deep in the Emacs 
source distribution.

I think the major reason this has not happened is because the Emacs
development culture is still largely stuck in a pre-Web mindset.
There are a number of historically contingent reasons for this, but
enumerating them is not really important.  What matters is recognizing
that this is a problem and fixing it.

There are two reasons it's a problem: one of capability, one of
positioning.

The positioning problem is that info/Texinfo makes us look like a
steam-powered archaic joke to younger developers.  Text-only
presentation with obtrusive links and a complex command set for a
viewer that's *not a web browser*?  In 2014?  Really?

The capability problem is that the younger developers are objectively right 
to laugh.  Because these resources are not rendered to Web, they're an
informational ghetto with an impoverished internal link structure.  The
fact that some of them, like /etc/CONTRIBUTE, are plain text with no
link structure at all certainly doesn't help.

The EmacsWiki is a valiant stab at fixing part of the problem, but its utility
is severely damaged by the fact that it can't readily link inwards to
the stuff carried in the distribution.

The solution must be partly a change in mechanism and partly a change
in policy and attitude.  The change in technology is the simple part;
info and Texinfo must die.  They must be replaced with a common format
for documentation masters that is Web-friendly, and by Web
presentation.

I have discussed this with RMS and, pending my ability to actually write
proper translation tools, we have agreed on asciidoc as a new master 
format.  This is what should replace Texinfo and the gallimaufry of
ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

The policy part of the job will in some ways be more difficult because
the requirements are harder to define.  We need to change the way we
think about Emacs's documentation; we need to concieve and organize it
as a single, coherent, richly linked hypertext that renders to HTML as
its major target.  This may mean giving up on some features supporting
rendering to print manuals; I'm not sure yet. If so, it's time to bite
that bullet.

I'm willing to take on the tools end, but I can't do it all.  Someone
needs to take ownership of the policy/organization end of the documentation 
problem. Will any of the people righly complaining about this step up?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[joakim]

"Eric S. Raymond" <esr@thyrsus.com> writes:

please see nics work in this area.

> Several recent posts in the metaproblem threads have had the common
> theme that Emacs's web resources are weak, scattered, and unfocused.
> In particular, guidance for new developers that should be public,
> prominent and webbed is buried in obscure text files deep in the Emacs 
> source distribution.
>
> I think the major reason this has not happened is because the Emacs
> development culture is still largely stuck in a pre-Web mindset.
> There are a number of historically contingent reasons for this, but
> enumerating them is not really important.  What matters is recognizing
> that this is a problem and fixing it.
>
> There are two reasons it's a problem: one of capability, one of
> positioning.
>
> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.  Text-only
> presentation with obtrusive links and a complex command set for a
> viewer that's *not a web browser*?  In 2014?  Really?
>
> The capability problem is that the younger developers are objectively right 
> to laugh.  Because these resources are not rendered to Web, they're an
> informational ghetto with an impoverished internal link structure.  The
> fact that some of them, like /etc/CONTRIBUTE, are plain text with no
> link structure at all certainly doesn't help.
>
> The EmacsWiki is a valiant stab at fixing part of the problem, but its utility
> is severely damaged by the fact that it can't readily link inwards to
> the stuff carried in the distribution.
>
> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.
>
> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.
>
> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.
>
> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the documentation 
> problem. Will any of the people righly complaining about this step up?

-- 
Joakim Verona

Re: On being web-friendly and why info must die

[Eric S. Raymond]

joakim@verona.se <joakim@verona.se>:
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> 
> please see nics work in this area.

A pointer would be useful.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

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

"Eric S. Raymond" <esr@thyrsus.com> writes:

> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.

Uh, this is the Emacs developer list.  Emacs' _principal_ appeal is to
the steampunk culture of information technology.

> Text-only presentation with obtrusive links and a complex command set
> for a viewer that's *not a web browser*?  In 2014?  Really?

Can it be that you lost contact with Texinfo some time ago already?
Here is how my info page for the current LilyPond manual looks in Emacs:


[-- Attachment #2: lilypond-info-sample.png --]
[-- Type: image/png, Size: 20279 bytes --]

[-- Attachment #3: Type: text/plain, Size: 5343 bytes --]


The HTML variant looks like
<URL:http://www.lilypond.org/doc/v2.19/Documentation/notation/note-heads.html#special-note-heads>.

Guess which variant is much much much more responsive to use when using
a standard HTML browser on the HTML variant (installed locally, of
course) as compared to using Emacs on the info version.

Guess which variant is integrated into the normal workflow much better.
Try searching the index in HTML.  That's so much worse it is not even
funny.  And the LilyPond manual is actually rather good for an HTML
based manual.

> The capability problem is that the younger developers are objectively
> right to laugh.  Because these resources are not rendered to Web,

Texinfo has an HTML backend.  The LilyPond manuals are generated in that
manner.  Pretty much every GNU project offering its Texinfo based
documentation online also offers an HTML version, typically both as a
single-file HTML version as well as a distributed version.

For about the last 20 years or so.

Here is the Emacs version:
<URL:http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html>.

If you compare it to the LilyPond version, you'll find that the Emacs
version
a) does not make use of a lot of images (any at all?)
b) looks rather bland

Both are (obviously) not shortcomings of Texinfo as such, but of the
default workflows, styles and tools.

For example: why can't I dump menu structures and buffers and example
frames suitable for Texinfo graphics right from within Emacs?

> The EmacsWiki is a valiant stab at fixing part of the problem, but its
> utility is severely damaged by the fact that it can't readily link
> inwards to the stuff carried in the distribution.

Of course you can link to the Emacs info manuals in HTML form.

> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.

You are confusing the documentation source (Texinfo) with one target
format (HTML).  HTML is not a reasonable format for authoring
documentation, just like Info isn't.  Texinfo, in contrast, is.  And
writing Texinfo is well-supported in Emacs.  I actually don't know any
other structured high-level documentation format that can reasonably be
edited in plain text form and converted into HTML using free tools.
Even if you care only for the HTML backend, you won't magically be able
to cater for it without having some human-writable frontend.  And there
is nothing wrong with using Texinfo for that.

> I have discussed this with RMS and, pending my ability to actually
> write proper translation tools, we have agreed on asciidoc as a new
> master format.

This is actually an awful idea as no reliable and maintained toolchains,
definitions, and Emacs editing modes for it exist and it is quite less
expressive than Texinfo.

> This is what should replace Texinfo and the gallimaufry of ad-hoc text
> files like /etc/CONTRIBUTE and the admin/notes stuff.

Files like /etc/CONTRIBUTE, if needed in multiple formats, can be
produced from Texinfo files using the ASCII backend.

AUCTeX does that for files like README, INSTALL, PROBLEMS and others
that are, in the fully marked-up version, included in the Texinfo
manuals as well.

> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.

I disagree.  Really.  Take a look at the documentation of LilyPond,
<URL:http://lilypond.org/doc/v2.19/Documentation/web/>> possibly
installing the full Info version as well and experiment with it.  You
can, of course, browse the web-based documentation also.

Every single bit of it, including _all_ the web pages (not just the
manuals) and their translations, is written and maintained in Texinfo.

> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the
> documentation problem. Will any of the people righly complaining about
> this step up?

I don't see that you'll magically get more people involved than those
maintaining Texinfo, and your basic proposal is not even in any way
related to HTML (which is available already) but rather to replacing the
source format of Texinfo with AsciiDoc, a format that does not
distinguish logical and physical markup, is its own plain-text output
format and thus is unsuitable for providing all the information that may
be relevant for _any_ of the backends you are likely to use with it.

It't not even "more hip" or "less steampunk" than Texinfo: its only
major use known to me is as the documentation system of Git.

And you need particular versions of its toolchain to even compile all
the documentation of Git last time I looked.

So before panicking into some purportedly newfangled direction, it would
make proper sense making better use of our existing tools.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Rasmus]

Hi,

"Eric S. Raymond" <esr@thyrsus.com> writes:

> [...] we have agreed on asciidoc as a new master format.

This seems nothing short of bizarre.
Did you, by chance, hear of this new mode called Org?

1. My Emacs does not feature an "asciidoc-mode", and it seems I would need
   an extra binary to export out of asciidoc to "richly linked hypertext".
   ox.el, the Org export framework, is written in Emacs-Lisp.
2. Judging from a sample on the Asciidoc-website, formatting asciidoc-txt
   seems painful.  E.g. a headline of length N seems to require 2×N
   characters and two lines whereas an Org headline requires N +
   HEADLINE-LEVEL + 1 characters and a single line.  Delimiters in
   asciidoc seems overloaded, e.g. ==⋯= is both the beginning of a table
   and an example block.
3. Org already supports export of texinfo, txt, html, LaTeX, odt, & man
   out of the box.  Asciidoc seems to support html...

—Rasmus

-- 
This space is left intentionally blank

Re: On being web-friendly and why info must die

[Phillip Lord]

"Eric S. Raymond" <esr@thyrsus.com> writes:
> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.
>
> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

I've written quite a lot of asciidoc in my time. It's not a bad format,
although it is not extensible, so I have resorted at times to using gpp
on source to get what I want (which messes up line numbers in error
reports, so there are problems with this approach).

Emacs support for asciidoc is not that good, to my knowledge. I have
been using adoc-mode, which does good syntax highlighting but is poor
for cross-referencing for instance. It also has a hang emacs bug (there
is a fix in my fork). So, I suspect that this would need fixing.

I recently went through these issues with a book I am writing. My
experiences are here.

http://www.russet.org.uk/blog/3020

I ended up with latex, although for documentation (which is much less
linear) I might reach a different conclusion. In particular, I would ask
about org -- the tools here already exist and the emacs support is
obviously good.


> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.
>
> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the documentation 
> problem. Will any of the people righly complaining about this step up?

I am almost certainly not the person to do this, but I am willing to
contribute to the documentation. I write well, or at least I think I do
but then who doesn't.

Phil

Re: On being web-friendly and why info must die

[joakim]

Rasmus <rasmus@gmx.us> writes:

> Hi,
>
> "Eric S. Raymond" <esr@thyrsus.com> writes:
>
>> [...] we have agreed on asciidoc as a new master format.
>
> This seems nothing short of bizarre.
> Did you, by chance, hear of this new mode called Org?
>
> 1. My Emacs does not feature an "asciidoc-mode", and it seems I would need
>    an extra binary to export out of asciidoc to "richly linked hypertext".
>    ox.el, the Org export framework, is written in Emacs-Lisp.
> 2. Judging from a sample on the Asciidoc-website, formatting asciidoc-txt
>    seems painful.  E.g. a headline of length N seems to require 2×N
>    characters and two lines whereas an Org headline requires N +
>    HEADLINE-LEVEL + 1 characters and a single line.  Delimiters in
>    asciidoc seems overloaded, e.g. ==⋯= is both the beginning of a table
>    and an example block.
> 3. Org already supports export of texinfo, txt, html, LaTeX, odt, & man
>    out of the box.  Asciidoc seems to support html...

texinfo isnt too bad. If we for some reason absolutely must change the
format, org is the only sane alternative, really.

>
> —Rasmus

-- 
Joakim Verona

Re: On being web-friendly and why info must die

[Rasmus]

Hi,

joakim@verona.se writes:
> Rasmus <rasmus@gmx.us> writes:
>> "Eric S. Raymond" <esr@thyrsus.com> writes:
>>> [...] we have agreed on asciidoc as a new master format.
>>
>> This seems nothing short of bizarre.
>> Did you, by chance, hear of this new mode called Org?
>>
>> 1. My Emacs does not feature an "asciidoc-mode", and it seems I would need
>>    an extra binary to export out of asciidoc to "richly linked hypertext".
>>    ox.el, the Org export framework, is written in Emacs-Lisp.
>> 2. Judging from a sample on the Asciidoc-website, formatting asciidoc-txt
>>    seems painful.  E.g. a headline of length N seems to require 2×N
>>    characters and two lines whereas an Org headline requires N +
>>    HEADLINE-LEVEL + 1 characters and a single line.  Delimiters in
>>    asciidoc seems overloaded, e.g. ==⋯= is both the beginning of a table
>>    and an example block.
>> 3. Org already supports export of texinfo, txt, html, LaTeX, odt, & man
>>    out of the box.  Asciidoc seems to support html...
>
> texinfo isnt too bad. If we for some reason absolutely must change the
> format, org is the only sane alternative, really.

My post is mean to be read /given/ ESR's premise.  David's post, which is
probably order of magnitudes more sane, questions ESR's premise.  I did
not see David's email before posting my own comment.

—Rasmus

-- 
And when I’m finished thinking, I have to die a lot

Re: On being web-friendly and why info must die

[Alan Mackenzie]

Hello, Eric.

On Fri, Dec 05, 2014 at 07:35:49AM -0500, Eric S. Raymond wrote:

[ ... ]

> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.  Text-only
> presentation with obtrusive links and a complex command set for a
> viewer that's *not a web browser*?  In 2014?  Really?

Links, by their very nature, are obtrusive.  A complex command set for a 
text-only editor is what Emacs (in essence) is.  I can't see what your
point is, here.

But it does strike me that many of your criticisms, below, of Texinfo
could equally be directed at Emacs as a whole.

> The capability problem is that the younger developers are objectively
> right to laugh.  Because these resources are not rendered to Web, ...

But they are.  Certainly, the Emacs manuals are online in HTML format.

> .... they're an informational ghetto with an impoverished internal link
> structure.

Impoverished?

> The fact that some of them, like /etc/CONTRIBUTE, are plain text with
> no link structure at all certainly doesn't help.

Maybe not.

[ ... ]

> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.

I don't want to have to read Emacs manuals in web presentation.  HTML is
a least common denominator format, lacking many (most?) of the things we
take for granted in info.  In fact, an alien landing on Earth for the
first time would be astonished to learn that info is the older format,
and would wonder what had caused us to regress.

If info is to die, then there must first be a better program to take its
place.  A web browser is not it.

> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

I've just looked at the asciidoc website.  It would appear there's no
text based rendering format, and I didn't find any mention of any
end-format tools, comparable with info, for reading such doc.

> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.

What features are we going to lose, compared with info?  What features,
if any, are we going to gain?

I don't think dumbing down our documentation source format is going to
help in attracting new devolpers.  But it will certainly soak up a _lot_
of effort to do.

> -- 
> 		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: On being web-friendly and why info must die

[Ivan Shmakov]

>>>>> Eric S Raymond <esr@thyrsus.com> writes:

[…]

 > The positioning problem is that info/Texinfo makes us look like a
 > steam-powered archaic joke to younger developers.  Text-only
 > presentation with obtrusive links and a complex command set for a
 > viewer that's *not a web browser*?  In 2014?  Really?

 > The capability problem is that the younger developers are objectively
 > right to laugh.  Because these resources are not rendered to Web,
 > they're an informational ghetto with an impoverished internal link
 > structure.

	I disagree on several points.  First of all, there /is/ a
	rendition of the Emacs documentation for Web browsers; see
	https://www.gnu.org/software/emacs/manual/.  If there’s anything
	specific to improve to make Emacs documentation more
	“Web-friendly” than that, I’d rather be interested in a list.

	(And similarly for the majority – if not all – GNU projects I’m
	personally interested in.  Given the well-known disagreement
	between Debian and GNU regarding the use of invariant sections
	and cover texts allowed by GNU FDL – /and/ currently used by
	several of GNU projects, I happen to use use these Web resources
	more than just occasionally.)

	Another point is the presence of the ‘Info-index’ command in the
	Emacs Info browser.  I know of no similar feature to be
	generally available for HTML-based browsers, – or HTML-based
	documentation, either.

	Also, the above made me curious of what exact features of the
	HTML presentation are felt missing in Info?  (In relation to GNU
	documentation, anyway.)

	Apart from the above, and given that Emacs now comes with an
	HTML browser of its own, I doubt that switching from Info-first
	to HTML-first documentation would affect my own workflow
	significantly.  I’m still concerned over the dependencies (EWW
	requires Libxml, while Info seem to be rather stand-alone) and
	performance (Info was started on much less powerful machines
	than the current “usual” equipment, and presumably will continue
	to work there just fine), but I guess these are minor points.

	(But if we’re really into the “positioning business” now, I’d
	like to refer to this new extensible self-documenting Atom
	editor.  Which, contrary to Emacs, /does/ work in a Web browser.
	I feel we may lose that battle before even starting it.)

 > The fact that some of them, like etc/CONTRIBUTE, are plain text with
 > no link structure at all certainly doesn't help.

 > The EmacsWiki is a valiant stab at fixing part of the problem, but
 > its utility is severely damaged by the fact that it can't readily
 > link inwards to the stuff carried in the distribution.

	To my mind, the biggest problem with EmacsWiki is the one of
	obtaining the copyright assignment papers for contributions
	deemed good enough to be included into Emacs proper.

	Also, to the best of my knowledge, there’re currently no
	existing VC backend for EmacsWiki.  (There is a crude but
	working one for MediaWiki, which is the software behind, say,
	Free Software Directory, Wikibooks and Wikipedia, etc.)

[…]

 > The policy part of the job will in some ways be more difficult
 > because the requirements are harder to define.  We need to change the
 > way we think about Emacs's documentation; we need to conceive and
 > organize it as a single, coherent, richly linked hypertext that
 > renders to HTML as its major target.

	I’m unsure if I understand the above.  Does it mean that instead
	of the separate manuals we now have for the Emacs proper, EWW,
	Gnus, and what not, we would end up with some kind of a Single
	Ultimate Emacs manual?  I’m unsure if I’d welcome such a change,
	for several reasons.

 > This may mean giving up on some features supporting rendering to
 > print manuals; I'm not sure yet.  If so, it's time to bite that
 > bullet.

	Somehow, I’ve got an impression that HTML-based typesetting is
	the area yet to be really covered by free software.  I’d
	certainly be interested in the efforts to change that.

[…]

-- 
FSF associate member #7257  np. Снаружи всех измерений — Гражданская Оборона

Re: On being web-friendly and why info must die

[Stefan Monnier]

> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

I must say I have a hard time believing that Richard made the decision
to ditch Texinfo and move to AsciiDoc.  Could we hear it from the
horse's mouth?  Is AsciiDoc (going to be) a GNU package?

But from Emacs's point of view, I'd be perfectly fine with using
something like AsciiDoc, RST, MarkDown, you name it: we have already
discussed the need to use such a markup for the "Commentary:" section of
Elisp packages, and indeed we've also already discussed the need to
replace Info with something higher-level such that we can more easily
change the text's appearance.

Of course, we wouldn't want to lose the ability to view the docs within
Emacs itself (rather than requiring Firefox) while disconnected from
the net.  And neither do we want to lose the `index' facility of Info.


        Stefan

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 07:35:49 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> 
> Several recent posts in the metaproblem threads have had the common
> theme that Emacs's web resources are weak, scattered, and unfocused.
> In particular, guidance for new developers that should be public,
> prominent and webbed is buried in obscure text files deep in the Emacs 
> source distribution.

David already said everything that crossed my mind while reading
this, and I can only agree with what he wrote.  What's below are a
couple of additional comments.

> I think the major reason this has not happened is because the Emacs
> development culture is still largely stuck in a pre-Web mindset.

I disagree.  The main reason is that none of the active developers
seems to have this aspect high on his agenda.  IOW, it's the oldest
reason in Free Software: no one has stepped forward to do that.

> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.
> 
> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the documentation 
> problem. Will any of the people righly complaining about this step up?

I think you are putting the wagon before the horse here.  Selection of
the tools and the language used to write documentation should be up to
the people who actually are writing most of the docs.  Those people
(full disclosure: I'm one of them) are acquainted to, and proficient
in Texinfo as the source language.  They currently know close to
nothing about AsciiDoc.  In addition, the manpower we have for working
on the documentation is already too thin, and it already started
showing in the quality of the Emacs manuals.

Moreover, the vast majority of contributions to Emacs aren't
accompanied by the corresponding documentation changes, they are left
for "the Powers That Be" (which, btw, is one major reason for slow
release process, because the missing docs need to be added/adapted
during the pretest).

Until more people start contributing to the docs, it makes very little
sense to me to change the tools, and by that cut the branch on which
we sit, documentation-wise.  That is, unless you will take it upon
yourself to be our documentation maintainer for the observable future.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Fri, 05 Dec 2014 14:01:00 +0000
> Cc: emacs-devel@gnu.org
> 
> I am almost certainly not the person to do this, but I am willing to
> contribute to the documentation. I write well, or at least I think I do
> but then who doesn't.

Thanks for the offer.  Please consider working on the documentation
changes required by the new features mentioned in NEWS.  Every entry
there that isn't marked with either "+++" or "---" needs a doc update.

TIA

Re: On being web-friendly and why info must die

[Rüdiger Sonderfeld]

On Friday 05 December 2014 07:35:49 Eric S. Raymond wrote:
> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.  Text-only
> presentation with obtrusive links and a complex command set for a
> viewer that's *not a web browser*?  In 2014?  Really?

texinfo does support images and in fact the info viewer in GNU Emacs supports 
those images.  But sadly this doesn't seem to be common knowledge and there 
are even projects who use images in their texinfo documents disabling them for 
the info support and only enabling them for html/pdf export.  E.g., I recently 
provided a patch to GNU Octave to change this but still there are cases where 
it shows a "no image" text instead.

But I have to agree that info(1) is just confusing and weird.  I only started 
liking info pages after I started to use the GNU Emacs info reader.

> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

Why not use org-mode instead?  It is part of GNU Emacs and it is very 
flexible.  E.g., /etc/CONTRIBUTE is actually written in outline-mode, which is 
the basis of org-mode.


I think the long term plan was to replace the info viewer in GNU Emacs with a 
viewer based on eww that could read the HTML versions of texinfo files.  The 
key point that is lacking though is the index.  HTML (or PDF) have no index 
support and an extension to support it would be required.

Regards,
Rüdiger

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks for the offer.  Please consider working on the documentation
> changes required by the new features mentioned in NEWS.  Every entry
> there that isn't marked with either "+++" or "---" needs a doc update.

Oh, is that the convention?  What's the difference between "+++" and
"---"?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> Thanks for the offer.  Please consider working on the documentation
>> changes required by the new features mentioned in NEWS.  Every entry
>> there that isn't marked with either "+++" or "---" needs a doc update.
>
> Oh, is that the convention?  What's the difference between "+++" and
> "---"?

Duh.

+++ indicates that all necessary documentation updates are complete.
    (This means all relevant manuals in doc/ AND lisp doc-strings.)
--- means no change in the manuals is needed.
When you add a new item, use the appropriate mark if you are sure it applies,
otherwise leave it unmarked.


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[David Kastrup]

Rüdiger Sonderfeld <ruediger@c-plusplus.de> writes:

> On Friday 05 December 2014 07:35:49 Eric S. Raymond wrote:
>> The positioning problem is that info/Texinfo makes us look like a
>> steam-powered archaic joke to younger developers.  Text-only
>> presentation with obtrusive links and a complex command set for a
>> viewer that's *not a web browser*?  In 2014?  Really?
>
> texinfo does support images and in fact the info viewer in GNU Emacs supports 
> those images.  But sadly this doesn't seem to be common knowledge and there 
> are even projects who use images in their texinfo documents disabling them for 
> the info support and only enabling them for html/pdf export.  E.g., I recently 
> provided a patch to GNU Octave to change this but still there are cases where 
> it shows a "no image" text instead.

Can it be related to "Yelp" (the GNOME documentation viewer) nominally
supporting images, but if you start it on documentation containing not
merely a few novelty images but documenting every feature with example
images (like the LilyPond info tree does), it will hang literally
forever?

Emacs is the _only_ Info reader I know that can handle the LilyPond
documentation including images.  The standalone info reader is not
phased by the LilyPond documentation, but it does not show the images
either.

> But I have to agree that info(1) is just confusing and weird.  I only
> started liking info pages after I started to use the GNU Emacs info
> reader.

Yes, and it is the only one really worth using.  But Texinfo has more
output formats than just Info.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Rüdiger Sonderfeld]

On Friday 05 December 2014 17:02:39 David Kastrup wrote:
> Can it be related to "Yelp" (the GNOME documentation viewer) nominally
> supporting images, but if you start it on documentation containing not
> merely a few novelty images but documenting every feature with example
> images (like the LilyPond info tree does), it will hang literally
> forever?
> 
> Emacs is the _only_ Info reader I know that can handle the LilyPond
> documentation including images.  The standalone info reader is not
> phased by the LilyPond documentation, but it does not show the images
> either.

I think the problem was that they never considered *.info to support images.  
That's why they never installed the images to the info directory in the first 
place and then started to add replacement text.  It seems pretty rare to 
actually see image files to be distributed with packaged info documents.  Just 
take a look at your /usr/share/info (depends on your distribution of course).  
Before I submitted the patch to GNU Octave the only image there I found was a 
single one for libidn.  I don't have LilyPond installed, but it seems that the 
Debian package (lilypond-doc) does not install the images to the info 
directory either: https://packages.debian.org/wheezy/all/lilypond-doc/filelist  
Not sure if Debian is to blame or if LilyPond doesn't install them.

> Yes, and it is the only one really worth using.  But Texinfo has more
> output formats than just Info.

The problem is that info(1) is what most people experience as info.  But yeah, 
in Emacs we have a good viewer considering the capabilities of the Info 
format.  And sadly other formats seem to lack index support.  That's a problem 
we need to solve if we abandon Info, independently of switching away from 
Texinfo.

I think Texinfo itself has a few issues as well.  I only started using it to 
write documentation for the 24.4 release.  I think Cross References (aka 
links) are a bit confusing.  Using a more popular language could lower the 
entry barrier.  But then again I have a bit of a doubt that a change to a 
different format would really attract more people to writing documentation and 
on the other hand it would certainly be a hassle for the majority of people 
already writing documentation.

Regards,
Rüdiger

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Alan Mackenzie <acm@muc.de>:
> I've just looked at the asciidoc website.  It would appear there's no
> text based rendering format, and I didn't find any mention of any
> end-format tools, comparable with info, for reading such doc.

The text rendering of asciidoc is asciidoc itself.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> > I have discussed this with RMS and, pending my ability to actually write
> > proper translation tools, we have agreed on asciidoc as a new master 
> > format.  This is what should replace Texinfo and the gallimaufry of
> > ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.
> 
> I must say I have a hard time believing that Richard made the decision
> to ditch Texinfo and move to AsciiDoc.  Could we hear it from the
> horse's mouth?  Is AsciiDoc (going to be) a GNU package?

We didn't discuss that.  The only resrervation RMS expressed to me
during our last exchange about this was about lowering the quality of
the PostScript renderings of the manuals.
 
> Of course, we wouldn't want to lose the ability to view the docs within
> Emacs itself (rather than requiring Firefox) while disconnected from
> the net.  And neither do we want to lose the `index' facility of Info.

I'm aware of these issues. 

The indexing support in stock asciidoc may not be quites strong
enough; this is one of the things I need to investigate

As to document browsing inside Emacs itself, Emacs is now a browser.  
So rendering HTML solves that problem too.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> Until more people start contributing to the docs, it makes very little
> sense to me to change the tools, and by that cut the branch on which
> we sit, documentation-wise.

You have this exactly backwards.  Texinfo/info are a barrier that impedes
more recruitment of hands to work on documentation.  This is one of the
reasons they must die.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Rüdiger Sonderfeld <ruediger@c-plusplus.de>:
> Why not use org-mode instead?

org mode has many virtues, but I don't believe it's powerful enough
for highly structured, long-form documents.  Apparently RMS doesn't
either, or he wouldn't have been receptive to the suggestion of
asciidoc.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Óscar Fuentes]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Rüdiger Sonderfeld <ruediger@c-plusplus.de>:
>> Why not use org-mode instead?
>
> org mode has many virtues, but I don't believe it's powerful enough
> for highly structured, long-form documents.

Precisely org-mode shines on structured, long-form documents. There are
several books written on org-mode, plus entire web sites.

> Apparently RMS doesn't
> either, or he wouldn't have been receptive to the suggestion of
> asciidoc.

RMS knows very little about org-mode, as he admitted on the past.

Org-mode is *far* more convenient and powerful than asciidoc. Consider
org-babel, for instance, that allows embedding code on the document on a
way that you can execute it and incorporate the output into the
document. That looks great for interactive manuals such as tutorials,
doesn't it?

Re: On being web-friendly and why info must die

[Stefan Monnier]

> 	Also, the above made me curious of what exact features of the
> 	HTML presentation are felt missing in Info?  (In relation to GNU
> 	documentation, anyway.)

The main issue with the Info format is that it's not designed to be
parsed.  Even the tiny bit of parsing that's expected (i.e. find menu
entries and hyperlinks) is not very well designed (e.g. restrictions on
the kind of characters that appear in a menu entry).

So we can present it "as is" in plain-text as was done back in Emacs-19,
but it's difficult to prettify the various elements in a reliable way.
We do try to do it (e.g. hide some of the verbosity of the hyperlink's
syntax, use different fonts for different elements), but this is
inevitably very limited because it's all done heuristically: e.g. the
Info format does not tell us which part of the text is "text" and which
part of the text is "quoted code", so we can't refill (which would
sometimes be needed after hiding the hyperlink syntax) and we can't use
proportional fonts for the text part since that would mess up the code
example parts.


        Stefan

Re: On being web-friendly and why info must die

[Glenn Morris]

Eli Zaretskii wrote:

> I think you are putting the wagon before the horse here.  Selection of
> the tools and the language used to write documentation should be up to
> the people who actually are writing most of the docs.  Those people
> (full disclosure: I'm one of them) are acquainted to, and proficient
> in Texinfo as the source language.  They currently know close to
> nothing about AsciiDoc.  In addition, the manpower we have for working
> on the documentation is already too thin, and it already started
> showing in the quality of the Emacs manuals.

I think this is a pretty crazy discussion.

Just want to say that I agree with you.
I've written a lot of Emacs documentation.
I like Texinfo, I'm used to Texinfo, Texinfo is not the problem.
I have no enthusiasm for throwing out all that experience just because
of some buzz-words being thrown around.

I worry about the recent apparent trend in Emacs to throw over
established ways of working, in favour of new methods proposed by people
who frankly don't contribute much to Emacs, don't seem to understand its
development practices, and don't seem to hold the people who actually do
work in much respect.

I'm especially disappointed to see this topic being raised at a time
when Stefan asked for less arguing and more actual work.

And that's about all I have to say on these silly "meta" topics.

Quick, someone write an angry blog post about people being stuck in the
mud, and unwilling to adapt to new ideas!

Please keep fighting the good fight, Eli.

Re: On being web-friendly and why info must die

[Stefan Monnier]

> But from Emacs's point of view, I'd be perfectly fine with using
> something like AsciiDoc, RST, MarkDown, you name it: we have already
                                        ^^^
                                        Org

Sorry guys, I really dropped the ball here,


        Stefan

Re: On being web-friendly and why info must die

[Stefan Monnier]

> The problem is that info(1) is what most people experience as info.

FWIW, I really think that the standalone Info viewer should be kept
secret, because it does a disservice to the reputation of the Info format.

And I really don't mean it to say that it's bad software: within the
constraints of "works only under a tty" and the very little bit of love
it gets, you can't expect it to shine.

But really, the standalone Info reader should start Emacs, and if Emacs
is not installed, it should emit an error message.  And only if Emacs is
not installed and the user did a secret dance would it then start the
true-real-standalone Info-viewer.

> I think Texinfo itself has a few issues as well.  I only started using it to 
> write documentation for the 24.4 release.  I think Cross References (aka 
> links) are a bit confusing.

I don't have strong opinions about different source formats, and they
all have their downsides.  The downsides of Texinfo for me are the weird
redundancy between @node/@section plus the text used in the menu entry:
(very) occasionally it's handy to be able to use 3 different texts for
"the name of the node", "the title of the section", "the text in the
menu entry", but there should be a way to just completely drop the
@node, for instance.  The other downside are indeed the crossrefs which
seem to be way overengineered.


        Stefan

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

Eric S. Raymond writes:

> Several recent posts in the metaproblem threads have had the common
> theme that Emacs's web resources are weak, scattered, and unfocused.
> In particular, guidance for new developers that should be public,
> prominent and webbed is buried in obscure text files deep in the Emacs 
> source distribution.
>
> I think the major reason this has not happened is because the Emacs
> development culture is still largely stuck in a pre-Web mindset.
> There are a number of historically contingent reasons for this, but
> enumerating them is not really important.  What matters is recognizing
> that this is a problem and fixing it.

100% agreed.

> There are two reasons it's a problem: one of capability, one of
> positioning.
>
> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.  Text-only
> presentation with obtrusive links and a complex command set for a
> viewer that's *not a web browser*?  In 2014?  Really?

Agreed here too.

> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

Here's where I'm a bit surprised... I'm not sure that new GNU projects
should have to use Texinfo, but why not put efforts into improving
Texinfo's HTML output?

 - Chris

PS: We use Sphinx for documentation in GNU MediaGoblin, and it has an
option for a texinfo output, but also provides *excellent* HTML output.)

PPS: I know some Guile developers have told me that Guile has a very
good set of texinfo processing modules, maybe could be helpful here in
modernizing GNU manual output, but I'm really not sure.

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

Eric S. Raymond writes:

> Rüdiger Sonderfeld <ruediger@c-plusplus.de>:
>> Why not use org-mode instead?
>
> org mode has many virtues, but I don't believe it's powerful enough
> for highly structured, long-form documents.  Apparently RMS doesn't
> either, or he wouldn't have been receptive to the suggestion of
> asciidoc.

I think the asciidoc choice is very confusing.

I think changing things for emacs to make it more modern is good... when
it came to changing to a new DVCS, I agree with the move to git Git; in
terms of usage, this is the clear winner.  But who is using asciidoc
these days?  At least orgmode has a large and active userbase
(especially among emacs users... indeed, orgmode seems to be emacs'
biggest selling point amongst new uers these days from what I've seen.)

Furthermore, I went looking for an example document... what I found was:

  http://www.methods.co.nz/asciidoc/book.html

To me, this does not look all so much cleaner and nicer than
TeXinfo... it still looks very 2002 to me.

Here is a project I am involved in that uses Sphinx, and this is fairly
default output:

  http://hy.readthedocs.org/en/latest/

Out of the box, this looks like a much more modern output.

(Again, Sphinx can support Texinfo if we really want it still, and I'm
sure many emacs users will... not that I am advocating Sphinx
specifically.)

But a lot of this is cosmetic.  We could improve Texinfo to look much
better probably (and that would positively affect a lot of existing GNU
projects).

But I really do not understand the choice of asciidoc.  Could you
explain further your reasoning?  It seems that to make asciidoc look
much nicer, it too will require quite a bit of theming... or could you
show examples to the contrary?  Any option of improving Texinfo's HTML
output, using Orgmode, using something currently popular like Sphinx,
makes much more sense to me.

But yes, by all means, let's make the emacs manuals' web output much
better.  (And GNU's generally!)

 - Chris

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Christopher Allan Webber <cwebber@dustycloud.org>:
> Here's where I'm a bit surprised... I'm not sure that new GNU projects
> should have to use Texinfo, but why not put efforts into improving
> Texinfo's HTML output?

Because Texinfo is a barrier in itself, full of ceremony and heavyweight
markup.  The state of the art has moved well past it - modern formats
like asciidoc (or perhaps even org - others may be right about that)
are both lighter and more powerful.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Ivan Shmakov]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

 >> Also, the above made me curious of what exact features of the HTML
 >> presentation are felt missing in Info?  (In relation to GNU
 >> documentation, anyway.)

 > The main issue with the Info format is that it's not designed to be
 > parsed.

	ACK, thanks.  I guess I should’ve really figured this simple
	thing out myself; and the rest becomes pretty obvious, indeed.

 > Even the tiny bit of parsing that's expected (i. e. find menu entries
 > and hyperlinks) is not very well designed (e. g. restrictions on the
 > kind of characters that appear in a menu entry).

 > So we can present it "as is" in plain-text as was done back in
 > Emacs-19, but it's difficult to prettify the various elements in a
 > reliable way.  We do try to do it (e. g. hide some of the verbosity
 > of the hyperlink's syntax,

	Curiously, this particular Info mode behavior was mentioned on
	IRC not so long ago (2014-10-28), where a participant claimed it
	was an unwanted feature with no documented means to disable
	(sans redefining Info-fontify-node.)  Which then prompted me to
	dig somewhat into the history.

	As I was able to find, while this feature was already available
	in 2004, the use of (setq Info-fontify-maximum-menu-size nil) to
	disable it was indeed only documented 2007-02-10.

	… The point is, I guess, that there’re those who still follow
	the ways of Emacs 19-or-so, and are just happy with that.

	Forcing all the Emacs years-long users to switch to EWW for
	reading Emacs’ own documentation would be (irrespective of how
	do I like EWW and HTML myself) a sure fail.

 > use different fonts for different elements), but this is inevitably
 > very limited because it's all done heuristically: e. g. the Info
 > format does not tell us which part of the text is "text" and which
 > part of the text is "quoted code", so we can't refill (which would
 > sometimes be needed after hiding the hyperlink syntax) and we can't
 > use proportional fonts for the text part since that would mess up the
 > code example parts.

	Somewhat tangential to the discussion, investigating possible
	means to make shr.el use (setq truncate-lines nil word-wrap t)
	for the text at the top of the “rendering tree” – instead of
	plain filling – is on my “to do” list.  (The current
	implementation effectively assumes a fixed-width font; see,
	e. g., shr-width.)

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Rüdiger Sonderfeld]

On Friday 05 December 2014 13:12:39 Glenn Morris wrote:
> Just want to say that I agree with you.
> I've written a lot of Emacs documentation.
> I like Texinfo, I'm used to Texinfo, Texinfo is not the problem.
> I have no enthusiasm for throwing out all that experience just because
> of some buzz-words being thrown around.

I agree.  Although Texinfo certainly is a slightly higher barrier and less 
people are familiar with it than potential alternatives, I don't think 
changing it would result in more people being willing to contribute to the 
documentation.  And if it annoys the people who are actually writing 
documentation, like you and Eli, then it doesn't make sense to change it.

That being said, I do think we should consider alternatives to using the Info 
format.  Now that we have eww/shr, it might make sense to use HTML as well.  
Although we need a way to support the index in it.

Regards,
Rüdiger

Re: On being web-friendly and why info must die

[Stefan Monnier]

> As to document browsing inside Emacs itself, Emacs is now a browser.
> So rendering HTML solves that problem too.

EWW/SHR looks a lot more crappy than Info-mode, so I don't think it's
quite that easy.


        Stefan

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Christopher Allan Webber <cwebber@dustycloud.org>:
> I think changing things for emacs to make it more modern is good... when
> it came to changing to a new DVCS, I agree with the move to git Git; in
> terms of usage, this is the clear winner.  But who is using asciidoc
> these days?

The Linux kernel, for one.  All their internal documentation and their webbed 
documentation is mastered in asciidoc. Also true of the git project.

> But a lot of this is cosmetic.  We could improve Texinfo to look much
> better probably (and that would positively affect a lot of existing GNU
> projects).

But it would still be Texinfo, still be an essentially pointless
barrier to learning how to contribute.  Stefan has recently observed
that the distinction between info node and document section structure
is almost always pointless duplication, and he's right.  This is one
of many reasons Texinfo needs to be razed to the ground.
 
> But I really do not understand the choice of asciidoc.  Could you
> explain further your reasoning?

I think (and I believe RMS agrees) that we need a master format that will
(a) play nice with Web, and (b) attract new contributors rather than
repelling them.

The latter criterion argues strongly for a modern, leightweignt markup
in general use outside the Emacs project.  org mode may be functionally
capable enough - I don't know yet - but I think it's the wrong kind 
of positioning; it says "We're Emacs, we're going to stick to our
weird ingrown rituals and not-invented-here hostility, go away".

What are the alternatives, really?  asciidoc.  rST. Sphinx.  Some
flavor of markdown.

I think markdown is right out because of the death-of-a-thousand dialects 
problem it has.  Yes, there's an attempt to solve that happening now.
But even supposing it succeeds, markdown isn't really designed for the 
kind of complex structured documents we have in Texinfo.

rST, Sphinx and asciidoc don't have that problem.  Among those, I think
asciidoc wins because it's achieved more desigh wins in high-profile
projects.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> > As to document browsing inside Emacs itself, Emacs is now a browser.
> > So rendering HTML solves that problem too.
> 
> EWW/SHR looks a lot more crappy than Info-mode, so I don't think it's
> quite that easy.

This problem can be fixed, and almost certainly will be simply because
HTML has such a a large constituency.  If we build it, they will come.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Rüdiger Sonderfeld <ruediger@c-plusplus.de>
> Date: Fri, 05 Dec 2014 18:12:27 +0100
> Cc: David Kastrup <dak@gnu.org>
> 
> But then again I have a bit of a doubt that a change to a different
> format would really attract more people to writing documentation and
> on the other hand it would certainly be a hassle for the majority of
> people already writing documentation.

Exactly my fears.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 12:55:04 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > Until more people start contributing to the docs, it makes very little
> > sense to me to change the tools, and by that cut the branch on which
> > we sit, documentation-wise.
> 
> You have this exactly backwards.  Texinfo/info are a barrier that impedes
> more recruitment of hands to work on documentation.  This is one of the
> reasons they must die.

I think you are wrong.  Texinfo is almost plain text, so writing
documentation in it is not hard, certainly not a barrier.  OTOH, the
lack of motivation among code developers to write documentation, which
leads to lack of know-how about writing good documentation, is a well
known fact.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 14:09:25 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> Christopher Allan Webber <cwebber@dustycloud.org>:
> > Here's where I'm a bit surprised... I'm not sure that new GNU projects
> > should have to use Texinfo, but why not put efforts into improving
> > Texinfo's HTML output?
> 
> Because Texinfo is a barrier in itself, full of ceremony and heavyweight
> markup.

Nonsense.

> The state of the art has moved well past it - modern formats like
> asciidoc (or perhaps even org - others may be right about that) are
> both lighter and more powerful.

How about showing those advantages, instead of throwing
unsubstantiated FAD?

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Rüdiger Sonderfeld <ruediger@c-plusplus.de>
> Cc: Glenn Morris <rgm@gnu.org>, Eli Zaretskii <eliz@gnu.org>
> Date: Fri, 05 Dec 2014 20:18:21 +0100
> 
> That being said, I do think we should consider alternatives to using the Info 
> format.  Now that we have eww/shr, it might make sense to use HTML as well.  
> Although we need a way to support the index in it.

That would be fine by me, at least.  The back-end can certainly be
replaced, provided that the replacement allows as efficient reading
and consulting the documentation as the Info format and its Emacs
viewer.

The issue here is mainly about the Texinfo source.  It doesn't make
sense to switch to another language, exactly as it doesn't make sense
to switch a C-based project to C++ or Java, when all the main
developers don't work and aren't proficient in these languages.  It's
a death blow to the project.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 14:36:43 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Rüdiger Sonderfeld <ruediger@c-plusplus.de>,
> 	emacs-devel@gnu.org
> 
> > But a lot of this is cosmetic.  We could improve Texinfo to look much
> > better probably (and that would positively affect a lot of existing GNU
> > projects).
> 
> But it would still be Texinfo, still be an essentially pointless
> barrier to learning how to contribute.

Nonsense.  What evidence do you have to back that up?

Here's the evidence I have: the GDB project, where it's policy to
require documentation changes with each user-visible change.  Every
contributor is required to comply, and there's a standing proposal for
those who don't feel themselves well in Texinfo to write their docs in
plain text, which the documentation maintainer (yours truly) will then
convert to Texinfo by adding the necessary markup.

The result?  Everyone complies without complaining, and I didn't yet
have even one person asking me to make good on that promise.

I see no reason why it cannot work in Emacs, if we ever decide to go
that way.  But even if we don't, this experience proves that your
assertions about Texinfo being a barrier are simply false.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 14:38:43 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca>:
> > > As to document browsing inside Emacs itself, Emacs is now a browser.
> > > So rendering HTML solves that problem too.
> > 
> > EWW/SHR looks a lot more crappy than Info-mode, so I don't think it's
> > quite that easy.
> 
> This problem can be fixed, and almost certainly will be simply because
> HTML has such a a large constituency.  If we build it, they will come.

Then go do it first, and then come back with your suggestions when you
are ready.  If we like it, maybe we will switch, who knows.

And once again, HTML output is available with Texinfo _today_.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Fri, 05 Dec 2014 13:12:01 -0500
> 
> > 	Also, the above made me curious of what exact features of the
> > 	HTML presentation are felt missing in Info?  (In relation to GNU
> > 	documentation, anyway.)
> 
> The main issue with the Info format is that it's not designed to be
> parsed.  Even the tiny bit of parsing that's expected (i.e. find menu
> entries and hyperlinks) is not very well designed (e.g. restrictions on
> the kind of characters that appear in a menu entry).

We can switch to some other back-end, if it is better (currently, none
of them is, AFAIK).  The main issue is not the back-end, it's the
source language.  Dropping the only language which is well known to
all those who write Emacs documentation is simply insane.

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

[snip]

> The issue here is mainly about the Texinfo source.  It doesn't make
> sense to switch to another language, exactly as it doesn't make sense
> to switch a C-based project to C++ or Java, when all the main
> developers don't work and aren't proficient in these languages.  It's
> a death blow to the project.

This is true when the new tool is difficult to master (as your C -> C++
example.) If the new tool has a similar learning curve than the old
tool, you must admit that the old tool is an incovenience for new
contributors in the same way that switching to the new tool is an
incovenience for the existing contributors.

Not that I'm advocating switching the documentation tool. IMHO there are
several things that we could improve to attract new hackers and ditching
texinfo is not one of then.

OTOH, what you say on other message about requiring documentation with
changes is an obvious improvement for the project, moreso if we offer
help on the process (formatting, as you say, but also grammar, etc.)
Requiring documentation might shy away some people, but overall the
Emacs development process would improve by shortening the release
cycles, IMHO.

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> > Because Texinfo is a barrier in itself, full of ceremony and heavyweight
> > markup.
> 
> Nonsense.

You have Texinfo markup in your fingertips.  So do I.  The difference
is, I can perform the cognitive distancing act required to see how it
looks to newbies.  Apparently you can't.

> > The state of the art has moved well past it - modern formats like
> > asciidoc (or perhaps even org - others may be right about that) are
> > both lighter and more powerful.
> 
> How about showing those advantages, instead of throwing
> unsubstantiated FAD?

Sure.  Go look at the asciidoc masters in the Linux or git source trees.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Romain Francoise]

On Fri, Dec 05, 2014 at 03:53:20PM -0500, Eric S. Raymond wrote:
> Go look at the asciidoc masters in the Linux or git source trees.

As far as I know, the Linux documentation is either unstructured
free-from plain text, or DocBook.

Or are you just referring to perf?

Re: On being web-friendly and why info must die

[Karl Fogel]

"Eric S. Raymond" <esr@thyrsus.com> writes:
>Christopher Allan Webber <cwebber@dustycloud.org>:
>> Here's where I'm a bit surprised... I'm not sure that new GNU projects
>> should have to use Texinfo, but why not put efforts into improving
>> Texinfo's HTML output?
>
>Because Texinfo is a barrier in itself, full of ceremony and heavyweight
>markup.  The state of the art has moved well past it - modern formats
>like asciidoc (or perhaps even org - others may be right about that)
>are both lighter and more powerful.

+1 on Org, Asciidoc, Markdown, or any other format that meets the
criteria:

  - Raw source is readable as-is

  - Has free software tools to generate good HTML
    (and we then treat HTML as the default output format)

  - Markup syntax is not burdensome

Equally important would be getting a situation where Emacs developers
can also easily edit the Emacs web pages at gnu.org (which by virtue of
URL will always have an officiality advantage for developers seeking
information, so we should use that advantage to our... advantage), by
having those pages be generated from markup source in our tree.

Actually, I think that might be *more* important than the exact choice
of markup language.  I hope we don't bikeshed.com the choice of markup
language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.

-K

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Romain Francoise <romain@orebokech.com>:
> On Fri, Dec 05, 2014 at 03:53:20PM -0500, Eric S. Raymond wrote:
> > Go look at the asciidoc masters in the Linux or git source trees.
> 
> As far as I know, the Linux documentation is either unstructured
> free-from plain text, or DocBook.
> 
> Or are you just referring to perf?

In at least some parts of the tree they've switched to asciidoc rather
than DocBook masters.  I thought it was all of them, but I could be
mistaken about that.

git has definitely gone the whole way there.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
> Actually, I think that might be *more* important than the exact choice
> of markup language.  I hope we don't bikeshed.com the choice of markup
> language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.

Agreed.  I may have given the impression that I'm more attached to
asciidoc per se than I am. It would be my first choice, but a reasoned
case could be made for a couple of the others.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

Rüdiger Sonderfeld <ruediger@c-plusplus.de> writes:

> I think Texinfo itself has a few issues as well.  I only started using
> it to write documentation for the 24.4 release.

What I consider the main nuisance right now is indexing.  Texinfo itself
is affected: you'd want to have an index entry for @it that is called
@it (and accessible from M-x info via i @it) but sorted under i (since
otherwise the index will basically just be full of @).

Texinfo 5 might be more amenable to making the indexing more flexible.
It's definitely also a nuisance for LilyPond (where we are talking about
the indexing of things like \relative, namely same indexing problem but
with a backslash as starter).

> I think Cross References (aka links) are a bit confusing.

Copy&paste from the info manual of Texinfo (as rendered by M-x info,
namely info format) is somewhat surreal regarding the mismatch between
the claims in the text and the actual output:

    8.6 '@ref'
    ==========

    '@ref' is nearly the same as '@xref' except that it does not generate a
    'See' in the printed output, just the reference itself.  This makes it
    useful as the last part of a sentence.

    For example,

         For more information, @pxref{This}, and @ref{That}.

    produces in Info:

         For more information, *note This::, and *note That::.

    and in printed output:

         For more information, see Section 1.1 [This], page 1, and Section
         1.2 [That], page 2.

      The '@ref' command can tempt writers to express themselves in a manner
    that is suitable for a printed manual but looks awkward in the Info
    format.  Bear in mind that your audience could be using both the printed
    and the Info format.  For example:

         Sea surges are described in @ref{Hurricanes}.

    looks ok in the printed output:

         Sea surges are described in Section 6.7 [Hurricanes], page 72.

    but is awkward to read in Info, "note" being a verb:

         Sea surges are described in *note Hurricanes::.

> Using a more popular language could lower the entry barrier.

HTML isn't an input language.  And AsciiDoc can hardly be called "more
popular".

> But then again I have a bit of a doubt that a change to a different
> format would really attract more people to writing documentation

More like "different people".

> and on the other hand it would certainly be a hassle for the majority
> of people already writing documentation.

When there are sizable numbers.  There is of course an ephemeral benefit
for this kind of "let's switch to something new" activism if basically
very little new material is being written in the current format, one can
batch-convert to a new input format and the new input format has a few
manyears of enthusiasm in it before the documentation writer base
sizzles out into into the same manpower that the old documentation crew
had at the point of change.

I don't see that AsciiDoc buys us even that.

-- 
David Kastrup

having heterogenous doc (was Re: On being web-friendly and why info must die)

[Nic Ferrier]

Wouldn't it be better to support more documentation formats?

The Emacs manual and the Elisp manual are very large, perhaps they could
be more usefully cut up.

This could happen over time, with the people doing it making smaller
manuals in texinfo or asciidoc or a few other formats?

And if the documentation reader allowed a consolidated index then it
would blur the lines between individual manuals.

Wouldn't that be a good thing?


I think I am opposed to Emacs being written in multiple programming
languages but it seems like it would be ok to have the documentation in
whatever format people were comfortable with.


Nic

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

Eric S. Raymond writes:

> rST, Sphinx and asciidoc don't have that problem.  Among those, I think
> asciidoc wins because it's achieved more desigh wins in high-profile
> projects.

The number of high profile projects on https://readthedocs.org/ using
sphinx these days is pretty crazy high... probably one reason Sphinx has
gotten such a large amount of development.

At any rate, I think if you're going to do one of these, there's still
the advantage that Sphinx can still generate texinfo, so that doesn't
have to be lost.

 - Chris

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Stefan Monnier <monnier@iro.umontreal.ca>:
>> > As to document browsing inside Emacs itself, Emacs is now a browser.
>> > So rendering HTML solves that problem too.
>> 
>> EWW/SHR looks a lot more crappy than Info-mode, so I don't think it's
>> quite that easy.
>
> This problem can be fixed, and almost certainly will be simply because
> HTML has such a a large constituency.

HTML is _not_ a source format.  Its current "constituency" is
_minuscule_ since every "web programmer" actually does not write HTML
but uses "authoring tools" and "frameworks" which produce a lot of crap
inconsistent with what everybody else produces and seeping in CSS,
JavaScript, Flash, incompatible browser extensions and what not.

That is absolutely not the way to arrive at consistent documentation.
If you want to arrive at consistent HTML documentation, you use some
well-defined logical authoring system/subset like Docbook or, guess
what, Texinfo and convert your HTML from there.

And that's what we have already.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> Until more people start contributing to the docs, it makes very little
>> sense to me to change the tools, and by that cut the branch on which
>> we sit, documentation-wise.
>
> You have this exactly backwards.  Texinfo/info are a barrier that impedes
> more recruitment of hands to work on documentation.  This is one of the
> reasons they must die.

HTML is not a suitable source format for documentation but a target
format, and AsciiDoc is an even larger barrier.  It's not well-defined
and has no canonical and/or reliable implementation.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Christopher Allan Webber <cwebber@dustycloud.org>:
>> I think changing things for emacs to make it more modern is good... when
>> it came to changing to a new DVCS, I agree with the move to git Git; in
>> terms of usage, this is the clear winner.  But who is using asciidoc
>> these days?
>
> The Linux kernel, for one.  All their internal documentation and their webbed 
> documentation is mastered in asciidoc.

Example?

> Also true of the git project.

That is the only project of which I know it uses AsciiDoc, and it has
versioning problems, not able to use the current AsciiDoc version for
everything.

>> But a lot of this is cosmetic.  We could improve Texinfo to look much
>> better probably (and that would positively affect a lot of existing
>> GNU projects).
>
> But it would still be Texinfo, still be an essentially pointless
> barrier to learning how to contribute.

As opposed to AsciiDoc?  Really?

>> But I really do not understand the choice of asciidoc.  Could you
>> explain further your reasoning?
>
> I think (and I believe RMS agrees) that we need a master format that
> will (a) play nice with Web, and (b) attract new contributors rather
> than repelling them.
>
> The latter criterion argues strongly for a modern, leightweignt markup
> in general use outside the Emacs project.

Which rules out AsciiDoc.  It is in less use outside the Emacs project
than even Texinfo.

> What are the alternatives, really?  asciidoc.  rST. Sphinx.  Some
> flavor of markdown.

So if we don't have better alternatives, why not stick with what we
have?

> I think markdown is right out because of the death-of-a-thousand
> dialects problem it has.

AsciiDoc is not even compatible with its "canonical" implementation in
different versions.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> 	Also, the above made me curious of what exact features of the
>> 	HTML presentation are felt missing in Info?  (In relation to GNU
>> 	documentation, anyway.)
>
> The main issue with the Info format is that it's not designed to be
> parsed.  Even the tiny bit of parsing that's expected (i.e. find menu
> entries and hyperlinks) is not very well designed (e.g. restrictions on
> the kind of characters that appear in a menu entry).

A new iteration of the Info format may well be reasonable.  It may also
be reasonable to ditch the Info format and just let Emacs deal similarly
well with the HTML output from Texinfo (it does not need a full HTML
parser for that).

But I don't see the point in ditching Texinfo as the source format.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eric S. Raymond]

David Kastrup <dak@gnu.org>:
> HTML is not a suitable source format for documentation but a target
> format,

That is true; I wasn't trying to suggest otherwise.  I was addressing
Stefan's point that HTML rendering in eww isn't that good yet.  I
think the natural consituency for eww and HTML as a browsing format is
so large that if we blow down our barriers to entry somebody will show
up to polish eww to a nice shine.  (In fact, I have a fair guess who that
will be.)

>         and AsciiDoc is an even larger barrier.  It's not well-defined
> and has no canonical and/or reliable implementation.

That is not.  It is quite well documented and specified.  It has a canonical
inplementation (asciidoc) and a slightly extended one (asciidoctor).
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> > Because Texinfo is a barrier in itself, full of ceremony and heavyweight
>> > markup.
>> 
>> Nonsense.
>
> You have Texinfo markup in your fingertips.  So do I.  The difference
> is, I can perform the cognitive distancing act required to see how it
> looks to newbies.  Apparently you can't.

When looking at existing Texinfo source, I get a good idea of how to
write Texinfo markup of my own.  When looking at AsciiDoc, I have no
clue since it is not apparent what is formatting, and what is content.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Karl Fogel <kfogel@red-bean.com> writes:

> "Eric S. Raymond" <esr@thyrsus.com> writes:
>>Christopher Allan Webber <cwebber@dustycloud.org>:
>>> Here's where I'm a bit surprised... I'm not sure that new GNU projects
>>> should have to use Texinfo, but why not put efforts into improving
>>> Texinfo's HTML output?
>>
>>Because Texinfo is a barrier in itself, full of ceremony and heavyweight
>>markup.  The state of the art has moved well past it - modern formats
>>like asciidoc (or perhaps even org - others may be right about that)
>>are both lighter and more powerful.
>
> +1 on Org, Asciidoc, Markdown, or any other format that meets the
> criteria:
>
>   - Raw source is readable as-is
>
>   - Has free software tools to generate good HTML
>     (and we then treat HTML as the default output format)
>
>   - Markup syntax is not burdensome

Texinfo?

> Equally important would be getting a situation where Emacs developers
> can also easily edit the Emacs web pages at gnu.org (which by virtue
> of URL will always have an officiality advantage for developers
> seeking information, so we should use that advantage to
> our... advantage), by having those pages be generated from markup
> source in our tree.

You mean, like _all_ of the web presence of GNU LilyPond
<URL:http://www.lilypond.org> is generated from Texinfo source?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eric S. Raymond]

David Kastrup <dak@gnu.org>:
> > But it would still be Texinfo, still be an essentially pointless
> > barrier to learning how to contribute.
> 
> As opposed to AsciiDoc?  Really?

Yes, asciidoc is far easier.  I speak as an experienced user of both.

> So if we don't have better alternatives, why not stick with what we
> have?

Because it's ugly, heavyweight, and a barrier to entry.  I know you
do not understand this.  Alas, your failure to understand it does not prevent
it from being a problem.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

Eric S. Raymond writes:

> Karl Fogel <kfogel@red-bean.com>:
>> Actually, I think that might be *more* important than the exact choice
>> of markup language.  I hope we don't bikeshed.com the choice of markup
>> language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.
>
> Agreed.  I may have given the impression that I'm more attached to
> asciidoc per se than I am. It would be my first choice, but a reasoned
> case could be made for a couple of the others.

Okay, sorry also that I may be responding to that a bit more than
anything.  Getting GNU's web documentation improved is an important
issue to me, and I really do want this to happen.

I do agree that the importance of good web documentation is more
important than info support, and if somehow we got tossed into the fork
of needing to pick one or the other, I think nice looking web
documentation is more important to the long-term health of GNU.

But!  I'm not convinced we need to lose info support (I somewhat
consider info and texinfo separate matters :)).  I don't think new users
should have to learn info, but if you know it, there's nothing else like
it as in terms of speed to navigate and keybindings.

Not to mention: using something that supports both nicely I think might
be the path of least resistance to get buy-in on this mailing list. :)

Sphinx can already generate very nice and pretty HTML and pretty decent
texinfo/info manuals.  Org-mode might require a lot more tweaking to get
to that point, I don't know.  It might be interesting to take stock of
existing options.

 - Chris

RE: On being web-friendly and why info must die

[Drew Adams]

> You mean, like _all_ of the web presence of GNU LilyPond
> <URL:http://www.lilypond.org> is generated from Texinfo source?

Very nice presentation.  Clean, clear, welcoming.

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

[snip]

> Sphinx can already generate very nice and pretty HTML and pretty decent
> texinfo/info manuals.  Org-mode might require a lot more tweaking to get
> to that point, I don't know.  It might be interesting to take stock of
> existing options.

FYI: Org-mode supports HTML, Texinfo and more:

http://orgmode.org/manual/Exporting.html

Re: On being web-friendly and why info must die

[Eric S. Raymond]

David Kastrup <dak@gnu.org>:
> When looking at existing Texinfo source, I get a good idea of how to
> write Texinfo markup of my own.  When looking at AsciiDoc, I have no
> clue since it is not apparent what is formatting, and what is content.

That's a feature, not a bug.

I used to be a fan of heavy, explicit document markup; DocBookXML was
my weapon of choice for large documents.  It took a bit of mental
readjustment when I first experimented with minimal, new-school
markups like markdown and asciidoc.

But then my perspective shifted. Now I like the fact that that the
markup obtrudes very little on the actual content.  I get to write *foo*
instead of <emphasis>foo</emphasis> and you know what?  It's better -
lower overhead not just in typed characters but in the amount of
attention required to read it structurally.

I also found that I had underestimated the practical value of not
having to render a document to get it to a plain-ASCII format
friendly to a human eyeball.  This cuts out a lot of friction that
you won't notice until it's gone.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 05 Dec 2014 21:41:58 +0100
> 
> > The issue here is mainly about the Texinfo source.  It doesn't make
> > sense to switch to another language, exactly as it doesn't make sense
> > to switch a C-based project to C++ or Java, when all the main
> > developers don't work and aren't proficient in these languages.  It's
> > a death blow to the project.
> 
> This is true when the new tool is difficult to master (as your C -> C++
> example.) If the new tool has a similar learning curve than the old
> tool, you must admit that the old tool is an incovenience for new
> contributors in the same way that switching to the new tool is an
> incovenience for the existing contributors.

I will agree to that when I see those new contributors in the
documentation department.

> OTOH, what you say on other message about requiring documentation with
> changes is an obvious improvement for the project, moreso if we offer
> help on the process (formatting, as you say, but also grammar, etc.)
> Requiring documentation might shy away some people, but overall the
> Emacs development process would improve by shortening the release
> cycles, IMHO.

Last time I suggested that, I was in minority.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 15:53:20 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: cwebber@dustycloud.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > > Because Texinfo is a barrier in itself, full of ceremony and heavyweight
> > > markup.
> > 
> > Nonsense.
> 
> You have Texinfo markup in your fingertips.  So do I.  The difference
> is, I can perform the cognitive distancing act required to see how it
> looks to newbies.  Apparently you can't.

Apparently, there are no technical arguments left in your arsenal (if
there were any to begin with), so you are down to ad hominem.  Shame
on you!

> > > The state of the art has moved well past it - modern formats like
> > > asciidoc (or perhaps even org - others may be right about that) are
> > > both lighter and more powerful.
> > 
> > How about showing those advantages, instead of throwing
> > unsubstantiated FAD?
> 
> Sure.  Go look at the asciidoc masters in the Linux or git source trees.

How typical.  See above.

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/05/2014 01:51 PM, Eric S. Raymond wrote:
>> So if we don't have better alternatives, why not stick with what we
>> >have?
> Because it's ugly, heavyweight, and a barrier to entry.

Although I know Texinfo well and asciidoc poorly and so am naturally 
biased in favor of Texinfo, I can certainly attest to Texinfo being 
heavyweight and having significant problems.  My 3-year-old desktop at 
work currently takes over a minute to create info/elisp.info from 
Emacs's Texinfo sources, and this is so annoyingly slow that it 
discourages me from checking my work when I edit the Elisp manual.

I know some Emacs developers purposely run older versions of Texinfo 
(which are faster) because of this performance problem, and this means 
we can't assume reasonably modern Texinfo features, e.g., good support 
for Unicode characters.

Even though Texinfo made a lot of sense for many years and we should not 
switch lightly, it may now be time to think of switching.  It'd be a win 
if we could use a format with a decently-fast support.

RE: On being web-friendly and why info must die

[Drew Adams]

> I don't think new users should have to learn info,

They do NOT "have to" learn it.

> but if you know it, there's nothing else like
> it as in terms of speed to navigate and keybindings.

Consider the user, new or not (but in particular, a newbie)
who has not learned or is not in the habit of *asking Emacs*
itself, and finds it "easier" to directly ask Stack Exchange
or help-gnu-emacs.

Level 1 help: Someone provides an answer.

Level 2 help: Someone provides an answer AND links to the
              pertinent Emacs or Elisp manual section on
              the web, so the user can (a) get a well
              thought out explanation and (b) learn more,
              starting from there.

Level 3 help: Level 2 help PLUS telling the user *how to
              ask Emacs* - how to consult the manual from
              Emacs and how to use `i' in it to find that
              information (and more) using the index.

No one *has to* learn Info to consult the manuals.

We do users a favor by teaching them that they can *ask
Emacs* (surprise!), and how to do that.

That door is not locked, and it is really very simple
to turn the doorknob.

You just need to know how to recognize the door.  There
is nothing difficult about finding information from the
manuals on the web.  That does not make web access or
HTML a substitute for Info.

This should be a no-brainer.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 17:39:55 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> I used to be a fan of heavy, explicit document markup; DocBookXML was
> my weapon of choice for large documents.  It took a bit of mental
> readjustment when I first experimented with minimal, new-school
> markups like markdown and asciidoc.
> 
> But then my perspective shifted. Now I like the fact that that the
> markup obtrudes very little on the actual content.  I get to write *foo*
> instead of <emphasis>foo</emphasis> and you know what?  It's better -
> lower overhead not just in typed characters but in the amount of
> attention required to read it structurally.

You are free to like or dislike whatever tools you want.  You like
*foo* more that "C-c C-e foo", that's your prerogative.  But until and
unless you are going to be a major contributor to Emacs documentation,
you do NOT get to choose our documentation system for us.

So just stop this useless discussion.  It isn't going anywhere useful.
It does certainly take away a significant portion of the time we have
to code and make those other improvements, like the CONTRIBUTE Web
page, mentoring newcomers, finding more volunteers and contributors,
etc.

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Paul Eggert <eggert@cs.ucla.edu>:
> Even though Texinfo made a lot of sense for many years and we should
> not switch lightly, it may now be time to think of switching.  It'd
> be a win if we could use a format with a decently-fast support.

I believe all the formats even remotely in contention have fast enough
toolchains for this not to be a barrier to entry.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

Óscar Fuentes writes:

> Christopher Allan Webber <cwebber@dustycloud.org> writes:
>
> [snip]
>
>> Sphinx can already generate very nice and pretty HTML and pretty decent
>> texinfo/info manuals.  Org-mode might require a lot more tweaking to get
>> to that point, I don't know.  It might be interesting to take stock of
>> existing options.
>
> FYI: Org-mode supports HTML, Texinfo and more:
>
> http://orgmode.org/manual/Exporting.html

Right... I more mean, how much work is there to make it usable for a
manual the size of emacs', and also make it look nice and modern?

I have seen some orgmode exports that looked *slick*, I think they were
using orgmode package plus some theming that made it look very nice, but
I'm not sure what it is.  The default orgmode export is not good enough,
I think.

I think there's also value in breaking things up into multiple pages,
so...

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

>> FYI: Org-mode supports HTML, Texinfo and more:
>>
>> http://orgmode.org/manual/Exporting.html
>
> Right... I more mean, how much work is there to make it usable for a
> manual the size of emacs', and also make it look nice and modern?

As mentioned on a previous post, Org is used to create books.

> I have seen some orgmode exports that looked *slick*, I think they were
> using orgmode package plus some theming that made it look very nice, but
> I'm not sure what it is.  The default orgmode export is not good enough,
> I think.

That can be customized as much as you like.

Apart from the default settings, the Org hackers will be happy to adapt
the package to our requirements. Can you say the same from the
Sphinx/AsciiDoc/rst/whatever maintainers?

> I think there's also value in breaking things up into multiple pages,
> so...

So?

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Dropping the only language which is well known to
> all those who write Emacs documentation is simply insane.

Yes.  Texinfo isn't the best language in the world, but you can make
drive-by contributors just write plain text, and it's OK.  And
maintainers can mark up things properly.

Texinfo is not a problem.  People wanting to replace Texinfo with <hip
markup language of seven years ago> is a problem.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Sat, Dec 6, 2014 at 4:02 AM, Lars Magne Ingebrigtsen <larsi@gnus.org> wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
>
>> Dropping the only language which is well known to
>> all those who write Emacs documentation is simply insane.
>
> Yes.  Texinfo isn't the best language in the world, but you can make
> drive-by contributors just write plain text, and it's OK.  And
> maintainers can mark up things properly.

Drive-by contributors could perhaps write in org-mode? That is pretty
easy to learn. (And conversion to texinfo is probably easy, or already
there.)

Re: On being web-friendly and why info must die

[Stefan Monnier]

I haven't followed this whole "doc format" saga because it's just too
exciting, sorry.

But I can't help point out that there are 2 issues: the source format.
And the doc-viewer (which may or may not require translation of the
source format to some other format).

Until there is a documentation viewer available in Elisp that is almost
as good as Info-mode while being prettier, the "online doc" format will
have to stay as Info, and as long as we stick with Info, then I don't
see a strong motivation to change the source format (even if it will
give us wagon loads of doc-contributors, there'd be a fairly large
amount of work in such a conversion).


        Stefan "Who doesn't know Texinfo and doesn't like it very much
                but always felt like it's close enough to ASCII that
                I don't need to worry too much about it, knowing that Eli
                will clean up after me if needed"

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> EWW/SHR looks a lot more crappy than Info-mode, so I don't think it's
>> quite that easy.
> This problem can be fixed,

Everything is possible.  But until it's fixed, it's simply not an option.


        Stefan "who thinks it could be pretty hard to fix"

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> But I can't help point out that there are 2 issues: the source format.
> And the doc-viewer (which may or may not require translation of the
> source format to some other format).

The doc viewer would be a web browser.  We don't have to solve that problem -
not having a separate doc viewer would be the point of the change, technically
speaking. 
 
> Until there is a documentation viewer available in Elisp that is almost
> as good as Info-mode while being prettier,

Does a web browser not qualify?  If not, why not?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> David Kastrup <dak@gnu.org>:
>> > But it would still be Texinfo, still be an essentially pointless
>> > barrier to learning how to contribute.
>> 
>> As opposed to AsciiDoc?  Really?
>
> Yes, asciidoc is far easier.  I speak as an experienced user of both.

I count 5 patches touching Documentation/ from you in Git, the only
major project basing its documentation on AsciiDoc.  That's less than
even my few patches.

Which, by the way, include

commit 4739809cd0ea12a8de006f9f086fdff9285189b8
Author: David Kastrup <dak@gnu.org>
Date:   Mon Aug 6 12:22:57 2007 +0200

    Add support for an info version of the user manual
    
    These patches use docbook2x in order to create an info version of the
    git user manual.  No existing Makefile targets (including "all") are
    touched, so you need to explicitly say
    
    make info
    sudo make install-info
    
    to get git.info created and installed.  If the info target directory
    does not already contain a "dir" file, no directory entry is created.
    This facilitates $(DESTDIR)-based installations.  The same could be
    achieved with
    
    sudo make INSTALL_INFO=: install-info
    
    explicitly.
    
    perl is used for patching up sub-par file and directory information in
    the Texinfo file.  It would be cleaner to place the respective info
    straight into user-manual.txt or the conversion configurations, but I
    find myself unable to find out how to do this with Asciidoc/Texinfo.
    
    Signed-off-by: David Kastrup <dak@gnu.org>

>> So if we don't have better alternatives, why not stick with what we
>> have?
>
> Because it's ugly, heavyweight, and a barrier to entry.  I know you
> do not understand this.

It must be hard for you being the only intelligent being in a world of
idiots, but it's not like this is a new experience for you.

> Alas, your failure to understand it does not prevent it from being a
> problem.

Rebasing Emacs documentation on a system for reasons only singularly
intelligent beings like you understand would appear to be a dangerous
move since you will not be available to save Emacs from the follies of
its programmers for all eternity.

So if you want to make a convincing pitch, you better come off your
condescending horse.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Lennart Borgman <lennart.borgman@gmail.com>
> Date: Sat, 6 Dec 2014 04:20:31 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>, 
> 	Emacs-Devel devel <emacs-devel@gnu.org>
> 
> > Yes.  Texinfo isn't the best language in the world, but you can make
> > drive-by contributors just write plain text, and it's OK.  And
> > maintainers can mark up things properly.
> 
> Drive-by contributors could perhaps write in org-mode? That is pretty
> easy to learn. (And conversion to texinfo is probably easy, or already
> there.)

They can write in pretty much _anything_, as long as the result is
close enough to plain ASCII.  Adding Texinfo markup is easy (I did
that myself a few times in documents of medium size), and could even
be automated if it becomes an issue.

This is not a real barrier (it could be an imaginary one).  The real
barrier is (a) a general tendency among software developers to shy
away of writing documentation, and (b) the fact that writing good
documentation needs a few skills that require practice to acquire.
As a kind of carrot, I can tell that good software developers that can
also write high-quality documentation are very valuable out there, so
if someone has a career on their mind, this is the place to polish
those skills with minimum overhead and for free.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Fri, 05 Dec 2014 23:28:44 -0500
> Cc: Christopher Allan Webber <cwebber@dustycloud.org>, emacs-devel@gnu.org
> 
> I can't help point out that there are 2 issues: the source format.
> And the doc-viewer (which may or may not require translation of the
> source format to some other format).
> 
> Until there is a documentation viewer available in Elisp that is almost
> as good as Info-mode while being prettier, the "online doc" format will
> have to stay as Info, and as long as we stick with Info, then I don't
> see a strong motivation to change the source format (even if it will
> give us wagon loads of doc-contributors, there'd be a fairly large
> amount of work in such a conversion).

Not surprisingly, I agree.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 01:10:19 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Christopher Allan Webber <cwebber@dustycloud.org>, emacs-devel@gnu.org
> 
> > Until there is a documentation viewer available in Elisp that is almost
> > as good as Info-mode while being prettier,
> 
> Does a web browser not qualify?

Not to me, not as progress from the current situation.

> If not, why not?

Because copy/pasting docs from a separate program while working on
something in Emacs is an annoyance -- it generally requires to reach
for the mouse, switch windows, etc.  And because some very useful
features, like "M-/", work well on stuff that is in an Emacs buffer,
but there are no comparable features for duplicating stiff in another
application.  And also because the index-searching commands, without
which you are lost in a large manual, don't exist in the Web browsers
out there.  And finally because Emacs documentation commands have
links that go to the respective manual and chapter, but no similar
features exist for external browsers.  (For the latter, you might
think these are easy to add, but that would need some not entirely
trivial solution for finding the place where the HTML docs are
installed on any given system.)

And I'm sure there are more reasons that people will come up with.

In sum, switching to a Web browser as the means to read documentation
is a regression.

Re: On being web-friendly and why info must die

[Fabrice Niessen]

Hello,

Óscar Fuentes wrote:
> Christopher Allan Webber <cwebber-oPPOFS2i0wrhBEyLrsoctQ@public.gmane.org> writes:
>
>>> FYI: Org-mode supports HTML, Texinfo and more:
>>>
>>> http://orgmode.org/manual/Exporting.html
>>
>> Right... I more mean, how much work is there to make it usable for a
>> manual the size of emacs', and also make it look nice and modern?
>
> As mentioned on a previous post, Org is used to create books.
>
>> I have seen some orgmode exports that looked *slick*, I think they were
>> using orgmode package plus some theming that made it look very nice, but
>> I'm not sure what it is.  The default orgmode export is not good enough,
>> I think.
>
> That can be customized as much as you like.
>
> Apart from the default settings, the Org hackers will be happy to adapt
> the package to our requirements. Can you say the same from the
> Sphinx/AsciiDoc/rst/whatever maintainers?

Not answering on the whole debate, just on that particular point: yes,
the HTML exported from Org mode is highly customizable (we can add CSS
and JS as we like).

I've done such an attempt to democratize nice HTML layout from Org mode
by just adding a couple of lines of declaration [1].

See the results at https://www.youtube.com/watch?v=DnSGSiXYuOk.

Best regards,
Fabrice

[1] https://github.com/fniessen/org-html-themes

-- 
Fabrice Niessen
Leuven, Belgium
http://www.pirilampo.org/

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 05 Dec 2014 14:47:51 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: emacs-devel@gnu.org
> 
> On 12/05/2014 01:51 PM, Eric S. Raymond wrote:
> >> So if we don't have better alternatives, why not stick with what we
> >> >have?
> > Because it's ugly, heavyweight, and a barrier to entry.
> 
> Although I know Texinfo well and asciidoc poorly and so am naturally 
> biased in favor of Texinfo, I can certainly attest to Texinfo being 
> heavyweight and having significant problems.  My 3-year-old desktop at 
> work currently takes over a minute to create info/elisp.info from 
> Emacs's Texinfo sources, and this is so annoyingly slow that it 
> discourages me from checking my work when I edit the Elisp manual.
> 
> I know some Emacs developers purposely run older versions of Texinfo 
> (which are faster) because of this performance problem, and this means 
> we can't assume reasonably modern Texinfo features, e.g., good support 
> for Unicode characters.

Since I'm one of those mentioned in the last paragraph, let me tell
you: this is a relatively minor problem for me.  I use an older
makeinfo mainly in protest: I couldn't believe the Texinfo users will
accept a new version that is uniformly 18 times slower than the
previous one.  Especially having gone through the outcry of Emacs
users when the new bidi display engine in Emacs 24 showed much smaller
(but still significant) slowdown in just some very corner use cases.

But if there is some language feature supported by a future Texinfo
that is a must, I will definitely switch to it, and suffer the
slowdown.

> Even though Texinfo made a lot of sense for many years and we should not 
> switch lightly, it may now be time to think of switching.  It'd be a win 
> if we could use a format with a decently-fast support.

The only reason why the Texinfo maintainer accepted the current slow
implementation is that no one was prepared to continue developing the
old C implementation, and so the only suggestion on the table was to
either accept the one based on Perl, which promised a future and a lot
of extensibility, or stagnate.

Therefore, an alternative to switching away from Texinfo would be to
volunteer to implement a much faster translator while keeping the
extensibility.  Texinfo is a small and a simple enough a language for
such a fast translator to be possible.  If someone with motivation and
enough interest is reading this, here is your cue.

And once again, no matter to which source language we switch, it will
not magically solve our documentation issues.  Contrary to what Eric
is saying, 90% of the effort of writing good documentation is not
producing markup -- each one is just a couple of keys in Emacs's
texinfo-mode.  No, the main part of the effort is thinking how to
describe a feature in a logical and didactically correct manner, and
then expressing that in clear and concise English text.  No markup
language will ever help us solve these problems, as they are
fundamentally human activities based on human creativity.  They need
human skills, not automated tools.

Re: having heterogenous doc (was Re: On being web-friendly and why info must die)

[David Kastrup]

Nic Ferrier <nferrier@ferrier.me.uk> writes:

> Wouldn't it be better to support more documentation formats?

As an editor, Emacs certainly should strive to support commonly used
documentation formats for editing purposes.  That does not require
fragmenting Emacs' documentation into different systems however.

> The Emacs manual and the Elisp manual are very large, perhaps they
> could be more usefully cut up.

They are cut up into nodes and chapters and are navigated through their
extensive indexes and hyperlinks.  Cutting them up into disparate pieces
of documentation makes it harder, not easier, to find relevant
information.

> This could happen over time, with the people doing it making smaller
> manuals in texinfo or asciidoc or a few other formats?

You mean, like the Elisp tutorial in doc/lispintro?  Or the more than a
dozen smaller manuals for particular Emacs subsystems in doc/misc?

> And if the documentation reader allowed a consolidated index then it
> would blur the lines between individual manuals.
>
> Wouldn't that be a good thing?

Possibly.  But using different or other documentation systems would not
appear to have anything to do with that.

> I think I am opposed to Emacs being written in multiple programming
> languages but it seems like it would be ok to have the documentation
> in whatever format people were comfortable with.

You are confusing the formats the documentation is written in with the
formats the documentation is read in.  Multiple output formats are
useful.  Multiple input formats lead to a fragmentation of efforts.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

> Eric S. Raymond writes:
>
>> rST, Sphinx and asciidoc don't have that problem.  Among those, I think
>> asciidoc wins because it's achieved more desigh wins in high-profile
>> projects.
>
> The number of high profile projects on https://readthedocs.org/ using
> sphinx these days is pretty crazy high... probably one reason Sphinx has
> gotten such a large amount of development.
>
> At any rate, I think if you're going to do one of these, there's still
> the advantage that Sphinx can still generate texinfo, so that doesn't
> have to be lost.

An output format is not the same as an input format.  We can generate
PostScript from our Texinfo documentation, but that does not mean that
this is of any use to people wanting to write our documentation in
PostScript.  The only usefulness is for a one-time conversion after
which you are going to continue maintenance in PostScript.

So Sphinx being able to write Texinfo is not useful for switching Emacs'
documentation over to Sphinx or maintaining it in Sphinx.

I also have a very hard time buying the idea that if Emacs was
documented in Sphinx or whatever the newfangled language of the day is,
we would suddenly gain a large influx of competent documentation
authors.

Because, guess what, the main impediment to writing high-quality
documentation for Emacs is not that it needs people willing to learn the
two dozen commands relevant for writing Texinfo in one of the
well-supported Emacs modes for it.

The main impediment is that it needs people willing to learn the ten
thousands of commands constituting Emacs.  And if the hurdle of Texinfo
is insurmountable for them, Emacs will be off the charts.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> David Kastrup <dak@gnu.org>:
>> When looking at existing Texinfo source, I get a good idea of how to
>> write Texinfo markup of my own.  When looking at AsciiDoc, I have no
>> clue since it is not apparent what is formatting, and what is content.
>
> That's a feature, not a bug.
>
> I used to be a fan of heavy, explicit document markup; DocBookXML was
> my weapon of choice for large documents.  It took a bit of mental
> readjustment when I first experimented with minimal, new-school
> markups like markdown and asciidoc.
>
> But then my perspective shifted.

Since you shifted your religious affiliation from a heavy-weight logical
markup language not intended for human perusal to an easier-on-the-eye
visual markup system, it does not follow that your conclusions are valid
for a light-weight logical markup language intended to be written by
humans.

> Now I like the fact that that the markup obtrudes very little on the
> actual content.  I get to write *foo* instead of
> <emphasis>foo</emphasis> and you know what?  It's better - lower
> overhead not just in typed characters but in the amount of attention
> required to read it structurally.

Good thing then that Emacs' documentation is not written in Docbook/XML.

> I also found that I had underestimated the practical value of not
> having to render a document to get it to a plain-ASCII format friendly
> to a human eyeball.  This cuts out a lot of friction that you won't
> notice until it's gone.

Well, things like

    In order to get the result @file{text}, you would write
    @samp{@@file@{text@}} in your source file.  File markups may be
    line-wrapped after slashes without introducing a hyphen if this is
    required in the PDF version.

are a bit tricky to express in an input-is-output visual markup
language.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

> Eric S. Raymond writes:
>
>> Karl Fogel <kfogel@red-bean.com>:
>>> Actually, I think that might be *more* important than the exact choice
>>> of markup language.  I hope we don't bikeshed.com the choice of markup
>>> language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.
>>
>> Agreed.  I may have given the impression that I'm more attached to
>> asciidoc per se than I am. It would be my first choice, but a reasoned
>> case could be made for a couple of the others.
>
> Okay, sorry also that I may be responding to that a bit more than
> anything.  Getting GNU's web documentation improved is an important
> issue to me, and I really do want this to happen.
>
> I do agree that the importance of good web documentation is more
> important than info support, and if somehow we got tossed into the fork
> of needing to pick one or the other, I think nice looking web
> documentation is more important to the long-term health of GNU.

So tell me what you consider wrong with the Texinfo-generated web
documentation of GNU LilyPond, arbitrary stuff like
<URL:http://www.lilypond.org/doc/v2.19/Documentation/notation/guitar>.
What parts of the documentation are "not nice looking" to a degree that
would be bad for LilyPond's long-term health?

I might add that we have several translations of all the web pages and
manuals which are tightly maintained (and some that are basically in
some left-behind state, not because of the amount of work Texinfo
presents since translators do not even need to touch the Texinfo parts
and, in contrast to some magic-cookie markup system like AsciiDoc are
not likely to break stuff just by copying things) but rather the amount
of work a good translation actually is.  Most of our translators (and
documentation-focused developers) come from a Windows background and/or
do not contribute significantly to code.

And that's certainly less technically inclined than the demographic
expected to write Emacs manuals.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Achim Gratz]

Christopher Allan Webber writes:
>> FYI: Org-mode supports HTML, Texinfo and more:
>>
>> http://orgmode.org/manual/Exporting.html
>
> Right... I more mean, how much work is there to make it usable for a
> manual the size of emacs', and also make it look nice and modern?

Thomas S. Dye has attempted to re-write the Org manual in Org itself and
I have added provisional support for it to be built eith the Org build
system.  The internal parsing and export machinery is undergoing a
significant change at this time in Org that did not made it into Emacs
yet, so at the moment that project lays dormant and the (outdated) Org
manual in Org does not build without extra patches.  Aside from that,
one of the problems is that very large documents with lots of headings
and subheadings export very slowly, due to superlinear complexity.  Some
of this would not be necessary during export (the document to be
exported is not edited and so some of the re-parsing necessary during
editing could be dropped perhaps).  If the manual was broken up into
individual parts that slowdown would become much less noticeable, but
that would require the manuals to be split into, let's say, one file per
section.  So the folks that are unhappy with Texinfo 5 because it is
slow would be even less happy with Org at this moment.  For comparison,
the Org manual is near the median of the size distribution for Emacs'
other manuals and the largest two (Gnus and Calc) are roughly twice the
size.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Stefan Monnier <monnier@iro.umontreal.ca>:
>> But I can't help point out that there are 2 issues: the source format.
>> And the doc-viewer (which may or may not require translation of the
>> source format to some other format).
>
> The doc viewer would be a web browser.

A web browser is not at my fingertips when I am working.  Emacs is.  A
web browser's display colors and fonts are optimized for prettiness
rather than efficiency and systematic navigation is not the first thing
on its mind.  As opposed to Info.

> We don't have to solve that problem - not having a separate doc viewer
> would be the point of the change, technically speaking.

As long as the other viewers suck so much, that's not a point in favor.
I actually do the proofreading of LilyPond web pages (which are
generated from Texinfo) in the Info rendition.  And that's also what I
use to look up any other documentation.

I have pointed out the LilyPond documentation and web presence several
times in this thread, and you have ignored it.  If you are unable to
point out any inherent deficiencies with it according to your "shiny is
better" metrics, it would appear that Texinfo-generated HTML is not
problematic as such.

>> Until there is a documentation viewer available in Elisp that is almost
>> as good as Info-mode while being prettier,
>
> Does a web browser not qualify?  If not, why not?

You are not being serious?  Instant response, permuted indexes with
autocompletion that are a keypress away, instantaneous document-wide
search (even while only one node is actively displayed at any time).

I frequently point people to particular nodes of our online HTML manuals
that could answer their question.  The way I do that is to find the
information in Info, then copy&paste some recognizably unique text
phrase into a web search engine, check that the reference this turns up
is the corresponding online version of the Info manual and then post the
HTML link.

There is no mechanism that will get me results straight from HTML
without at least a tenfold investment of time and effort.

There are search boxes and indexes in the HTML version as well but they
are much much more cumbersome (for using the indexes) and/or with worse
results (for using the search box).

The only meaningful way to use browser search is to look in a
"single-page" version, and that costs a bunch of rendering time, and try
dragging a scrollbar on some document a few hundred pages long.
Navigation becomes really awkward.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Paul Eggert]

Eli Zaretskii wrote:
> 90% of the effort of writing good documentation is not producing markup

True, but if we can make the process of writing documentation even 5% more 
efficient or 5% more inviting, that could well be such a long-term win that it's 
worth the conversion hassle.

> if there is some language feature supported by a future Texinfo
> that is a must, I will definitely switch to it

As I recall, you had another objection to Texinfo 5: it quotes with curly quotes 
“like this”, not with ASCII quotes "like this", and you are concerned that some 
older Info readers might be confused by the non-ASCII quotes.

Anyway, no matter what the reason for not upgrading, in the meantime we're stuck 
with old-technology Texinfo, and this is partly why it might be a good idea to 
think about changing.

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> "Eric S. Raymond" <esr@thyrsus.com>:

> What are the alternatives, really?  asciidoc.  rST. Sphinx.  Some
> flavor of markdown.

org-mode.

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> David Kastrup <dak@gnu.org>:

> Good thing then that Emacs' documentation is not written in
> Docbook/XML.

Actually, it probably isn't.

Emacs with a properly set up nxml or psgml (not sure if psgml can be
convinced to support newer DocBooken, but if it can, psgml actually has
better tree-navigation than nxml) is a great tool for editing DocBook.

And DocBook is a great basis for creating good presentations in various
formats.  Lots of good, free, tool support.

(But I've given up trying to convince people that DB is the way of the
future... which means it probably isn't... (not just because of me, but
because the way the wind blows))


- Steinar (org-mode user)

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sat, 06 Dec 2014 02:24:11 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: esr@thyrsus.com, emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> > 90% of the effort of writing good documentation is not producing markup
> 
> True, but if we can make the process of writing documentation even 5% more 
> efficient or 5% more inviting, that could well be such a long-term win that it's 
> worth the conversion hassle.

Sure, any optimization is for the best.  But the main problems are not
solved by that, and this thread seems to be aimed at much more than
just 7% improvements.

Moreover, a 7% or a 10% percent improvement does not justify a change
ion our toolchain.

> > if there is some language feature supported by a future Texinfo
> > that is a must, I will definitely switch to it
> 
> As I recall, you had another objection to Texinfo 5: it quotes with curly quotes 
> “like this”, not with ASCII quotes "like this", and you are concerned that some 
> older Info readers might be confused by the non-ASCII quotes.

Yes, but as time goes by, the old viewers disappear into oblivion and
cease being relevant.  E.g., someone submitted a patch to make the
stand-alone Info reader reasonably support curly quotes even on a
Windows console.

> Anyway, no matter what the reason for not upgrading, in the meantime we're stuck 
> with old-technology Texinfo, and this is partly why it might be a good idea to 
> think about changing.

I'm not opposed to thinking about a change; who would be?  And not
just think, IMO: we should try to improve Texinfo and its back-ends as
much as we can.  But that's not my point.

My point is that if the alternative is AsciiDoc, then at this time the
switch would be a disaster for the quality of the Emacs documentation.
Heck, we don't even have a decent Emacs mode for writing AsciiDoc (the
2 modes available out there IMO don't come close to what we have for
Texinfo).  Until all of this gets taken care of by the enthusiasts, or
until some other document-writing system emerges that is significantly
better, it makes very little sense to switch.

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Paul Eggert <eggert@cs.ucla.edu>:
> Eli Zaretskii wrote:
> >90% of the effort of writing good documentation is not producing markup
> 
> True, but if we can make the process of writing documentation even
> 5% more efficient or 5% more inviting, that could well be such a
> long-term win that it's worth the conversion hassle.

More generally, none of the individual steps to enable new contributions
are sufficient, but they're all necessary.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> David Kastrup <dak@gnu.org>:

> HTML is _not_ a source format.  Its current "constituency" is
> _minuscule_ since every "web programmer" actually does not write HTML
> but uses "authoring tools" and "frameworks" which produce a lot of crap
> inconsistent with what everybody else produces and seeping in CSS,
> JavaScript, Flash, incompatible browser extensions and what not.

At least Flash seems to be on its way out.

(of course, the people misusing Flash seems to have found a new
playground in HTML5...)

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Steinar Bang <sb@dod.no>:
> > What are the alternatives, really?  asciidoc.  rST. Sphinx.  Some
> > flavor of markdown.
> 
> org-mode.

To be fair, that does look like a more viable technical choice than when 
first I raised the issue.  But I still have a concern that we would fail in the
ultimate goal of the change if the outside reaction is "Emacs tribe off
doing its own insular thing again".  I think we need a choice that faces
outwards, not inwards.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 05:49:03 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> Paul Eggert <eggert@cs.ucla.edu>:
> > Eli Zaretskii wrote:
> > >90% of the effort of writing good documentation is not producing markup
> > 
> > True, but if we can make the process of writing documentation even
> > 5% more efficient or 5% more inviting, that could well be such a
> > long-term win that it's worth the conversion hassle.
> 
> More generally, none of the individual steps to enable new contributions
> are sufficient, but they're all necessary.

But the order is still important.  As we all learned at some point,
you start the optimization process by attacking the hot spots first.
And for a good reason: doing that brings you the most return on your
investments.

So let's practice some good engineering and some good management, and
do first things first, shall we?

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> > > Until there is a documentation viewer available in Elisp that is almost
> > > as good as Info-mode while being prettier,
> > 
> > Does a web browser not qualify?
> 
> Not to me, not as progress from the current situation.
> 
> > If not, why not?
> 
> Because copy/pasting docs from a separate program while working on
> something in Emacs is an annoyance

Granted.  But eww is part of the background conditions now.  Emacs
itself is a browser, and will become a better one.

> And also because the index-searching commands, without which you are
> lost in a large manual, don't exist in the Web browsers out there.

This is not at *all* hard to solve.  I have written HTML generators
that produce index links myself in different contexts.

> And finally because Emacs documentation commands have
> links that go to the respective manual and chapter, but no similar
> features exist for external browsers.

Generating that kind of link structure from any modern markup is
almost trivial.  If you don't understand this it is unsurprising that
you are opposed.  But it is quite surprising that you don't understand.

> In sum, switching to a Web browser as the means to read documentation
> is a regression.

Except to pretty much the entire universe of new developers we need to recruit.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> > > Until there is a documentation viewer available in Elisp that is almost
>> > > as good as Info-mode while being prettier,
>> > 
>> > Does a web browser not qualify?
>> 
>> Not to me, not as progress from the current situation.
>> 
>> > If not, why not?
>> 
>> Because copy/pasting docs from a separate program while working on
>> something in Emacs is an annoyance
>
> Granted.  But eww is part of the background conditions now.  Emacs
> itself is a browser, and will become a better one.
>
>> And also because the index-searching commands, without which you are
>> lost in a large manual, don't exist in the Web browsers out there.
>
> This is not at *all* hard to solve.  I have written HTML generators
> that produce index links myself in different contexts.

Good grief.  Texinfo _does_ produce indexes in its HTML output.  But the
browsers offer no reasonable navigation for them as they are just
hyperlinked pages like the rest.

> Generating that kind of link structure from any modern markup is
> almost trivial.  If you don't understand this it is unsurprising that
> you are opposed.  But it is quite surprising that you don't
> understand.

If you could stop presuming the sole reason somebody could disagree with
you is because he is an idiot, it would make it easier to lead something
akin to a civilized discussion.

Getting the information condensed into some form of HTML is not the
problem.  The problem is actually having it accessible in the browser in
a manner catered to the actual use rather than like every other HTML.

It is not so much the Info format competing with HTML (though
instantaneous rendering and response do have their perks).  It is the
Emacs Info reader competing with generic HTML browsers.

That's the measuring yard, not the standalone Info reader.

>> In sum, switching to a Web browser as the means to read documentation
>> is a regression.
>
> Except to pretty much the entire universe of new developers we need to
> recruit.

The hurdle there is Elisp, not Texinfo.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eric S. Raymond]

David Kastrup <dak@gnu.org>:
> I have pointed out the LilyPond documentation and web presence several
> times in this thread, and you have ignored it.

I'm sorry you have that impression.  In fact I have "Look at how Lilypond
does it" on my to-do list.  But it has been a busy week and I haven't had
time to yet.  Weekend won't be any better as I'm being filmed for a
documentary.  Next week, probably, if it's not crowded out by preparing
for my 6th-level test in wing chun kung fu.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I once looked at the documentation for Org mode, and gave up.  It presented
doing things I didn't find useful.  I did not see, at the beginning, how
to use it as markup for manuals.  Perhaps it says that later, but I did not
get that far.

I could consider Org mode as a way of formatting manuals if I saw
documentation presenting Org mode _as_ a way to format manuals.
However, it would still have two big drawbacks as a candidate for GNU
documentation.

* It is a program.  What we need is a format.

* The program runs only in Emacs.

Texinfo is a format and you can use any editor to write that format.

I don't want to take a step back on either of these points.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Both of you are takig a harsh tone in these messages.  If anything
will drive people away from contributing, it is that.

Please, both of you, and everyone, take the aggression out of your
arguments.


> Eli Zaretskii <eliz@gnu.org>:
> > > Because Texinfo is a barrier in itself, full of ceremony and heavyweight
> > > markup.
> > 
> > Nonsense.
> 
> You have Texinfo markup in your fingertips.  So do I.  The difference
> is, I can perform the cognitive distancing act required to see how it
> looks to newbies.  Apparently you can't.

Apparently, there are no technical arguments left in your arsenal (if
there were any to begin with), so you are down to ad hominem.  Shame
on you!

> > > The state of the art has moved well past it - modern formats like
> > > asciidoc (or perhaps even org - others may be right about that) are
> > > both lighter and more powerful.
> > 
> > How about showing those advantages, instead of throwing
> > unsubstantiated FAD?
> 
> Sure.  Go look at the asciidoc masters in the Linux or git source trees.

How typical.  See above.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 06:03:10 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: monnier@iro.umontreal.ca, cwebber@dustycloud.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > > > Until there is a documentation viewer available in Elisp that is almost
> > > > as good as Info-mode while being prettier,
> > > 
> > > Does a web browser not qualify?
> > 
> > Not to me, not as progress from the current situation.
> > 
> > > If not, why not?
> > 
> > Because copy/pasting docs from a separate program while working on
> > something in Emacs is an annoyance
> 
> Granted.  But eww is part of the background conditions now.  Emacs
> itself is a browser, and will become a better one.

Your premise was an external browser, not eww.

If we are going for eww as the primary browser, it needs to become
much more mature and better before it can count.  It will also have to
acquire features specific for supporting reading of documentation,
something that currently is not even on ewww developers' agenda,
AFAIK.

> > And also because the index-searching commands, without which you are
> > lost in a large manual, don't exist in the Web browsers out there.
> 
> This is not at *all* hard to solve.  I have written HTML generators
> that produce index links myself in different contexts.

Producing links is not the problem (makeinfo already does that).  The
problem is _searching_ by index entries.  The 'i' command in the Info
viewer.  Without that command, you cannot use a manual as a reference,
where you know approximately what you are looking for, but don't know
its chapter/section name.

> > And finally because Emacs documentation commands have
> > links that go to the respective manual and chapter, but no similar
> > features exist for external browsers.
> 
> Generating that kind of link structure from any modern markup is
> almost trivial.  If you don't understand this it is unsurprising that
> you are opposed.

You elided the only portion of that which I consider non-trivial.  For
the trouble it could cause, read any of the threads about having
multiple Info manuals installed on the same system.  If you don't
understand how this could be a problem, it is not surprising that you
think it's trivial.

> > In sum, switching to a Web browser as the means to read documentation
> > is a regression.
> 
> Except to pretty much the entire universe of new developers we need to recruit.

This isn't the way, certainly not the most important one.

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> David Kastrup <dak@gnu.org>:
>> I have pointed out the LilyPond documentation and web presence
>> several times in this thread, and you have ignored it.
>
> I'm sorry you have that impression.  In fact I have "Look at how
> Lilypond does it" on my to-do list.

That might be a good opportunity for postponing your shouting match
until you have a more accurate view of existing current Texinfo
frameworks.  After all, it may seriously affect the work and success
estimates for either approach.

> But it has been a busy week and I haven't had time to yet.  Weekend
> won't be any better as I'm being filmed for a documentary.  Next week,
> probably, if it's not crowded out by preparing for my 6th-level test
> in wing chun kung fu.

I am sure you'll find your opponent in a Kung Fu fight surprised if you
tell him that you'll parry his blow next week since you had no time for
proper preparation.

Texinfo will still be there in a few weeks, so it might be smarter to
focus on the more imminent combat.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[James Fuller]

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

long time lurker/user,

balancing off what works for a 'long time' versus being relevant to new
contributors is a tough one ... though I thoroughly agree with the spirit
of Eric's thinking.

a bit of TMTOWDI thinking ... why not have 1+n documentation formats ?

let those formats wither that do not get adopted and avoid having the 'one
true' format discussion.

of course, there are engineering compromises, though it sounds like a fun
problem to work out.

Jim Fuller




On Sat, Dec 6, 2014 at 1:06 PM, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> Both of you are takig a harsh tone in these messages.  If anything
> will drive people away from contributing, it is that.
>
> Please, both of you, and everyone, take the aggression out of your
> arguments.
>
>
> > Eli Zaretskii <eliz@gnu.org>:
> > > > Because Texinfo is a barrier in itself, full of ceremony and
> heavyweight
> > > > markup.
> > >
> > > Nonsense.
> >
> > You have Texinfo markup in your fingertips.  So do I.  The difference
> > is, I can perform the cognitive distancing act required to see how it
> > looks to newbies.  Apparently you can't.
>
> Apparently, there are no technical arguments left in your arsenal (if
> there were any to begin with), so you are down to ad hominem.  Shame
> on you!
>
> > > > The state of the art has moved well past it - modern formats like
> > > > asciidoc (or perhaps even org - others may be right about that) are
> > > > both lighter and more powerful.
> > >
> > > How about showing those advantages, instead of throwing
> > > unsubstantiated FAD?
> >
> > Sure.  Go look at the asciidoc masters in the Linux or git source trees.
>
> How typical.  See above.
>
>
> --
> Dr Richard Stallman
> President, Free Software Foundation
> 51 Franklin St
> Boston MA 02110
> USA
> www.fsf.org  www.gnu.org
> Skype: No way! That's nonfree (freedom-denying) software.
>   Use Ekiga or an ordinary phone call.
>
>
>

[-- Attachment #2: Type: text/html, Size: 3114 bytes --]

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 05:54:33 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> 
> > org-mode.
> 
> To be fair, that does look like a more viable technical choice than when 
> first I raised the issue.  But I still have a concern that we would fail in the
> ultimate goal of the change if the outside reaction is "Emacs tribe off
> doing its own insular thing again".  I think we need a choice that faces
> outwards, not inwards.

IMO, it should be our firm assumption that whoever works on
Emacs-related documentation does that in Emacs.  Not in vim, not in
Notepad, not in gedit, in Emacs.  I have hard time imagining a
documentation contributor who is not him/herself an Emacs user.

If that's our assumption, then using some Emacs mode is a no-brainer,
and it is not an insular thing, as far as we are concerned.

Personally, my only doubts about Or mode being an alternative are
related to (1) how easy it is to learn that stuff, and (2) the
performance we will get from the translator to whatever back-end
format we will decide to adopt.

(I do use Org, but not in these areas, so I don't know the answers to
those questions.)

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
> I could consider Org mode as a way of formatting manuals if I saw
> documentation presenting Org mode _as_ a way to format manuals.

Org mode can be used to format whole manuals, but it has many other uses
and its user base is very diverse in how they apply Org to their
documents and workflows.  Documentation for specific workflows or uses
is usally initiated by Org users and , but none have been forthcoming for
formatting of manuals so far (it's been discussed briefly on the Org
mailing list a few times, though).  If you'd like me to, I could ask on
the Org mailing list if anybody would want to have a go at it.

> However, it would still have two big drawbacks as a candidate for GNU
> documentation.
>
> * It is a program.  What we need is a format.

Org has been a format for a while, just one that wasn't formally
defined.  However, that is being worked on by Nicolas Goaziou and the
next major release is intended to make the switch to a formally defined
format and a reference implementation in eLisp.  The draft version of
that specification is here:

http://orgmode.org/worg/dev/org-syntax.html

Feedback specifically directed at that definition should go to the Org
mailing list.

> * The program runs only in Emacs.

There are a small number of programs and web applications that support
or use the Org format (or approximations thereof) for various things.
With the format soon having a more formal definition this situation
should improve further one would hope.

> Texinfo is a format and you can use any editor to write that format.

That is true for Org as well.  You might lose some of the amenities that
Emacs delivers for easier navigation and editing shortcuts, but it is
quite possible to edit Org outside Emacs or even generate it
programmatically.

> I don't want to take a step back on either of these points.

You wouldn't need to, unless I misunderstood what you are after.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for KORG EX-800 and Poly-800MkII V0.9:
http://Synth.Stromeko.net/Downloads.html#KorgSDada

Re: On being web-friendly and why info must die

[Ivan Shmakov]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

[…]

 > If we are going for eww as the primary browser, it needs to become
 > much more mature and better before it can count.  It will also have
 > to acquire features specific for supporting reading of documentation,
 > something that currently is not even on eww developers' agenda,
 > AFAIK.

	JFTR, if you have any specific improvements in mind, – please
	file them as (wishlist) bugs.  I do not promise anything, but I
	use EWW as my primary browser for over a year now, and I sure
	hope to help make it better.

[…]

 > The problem is _searching_ by index entries.  The 'i' command in the
 > Info viewer.  Without that command, you cannot use a manual as a
 > reference, where you know approximately what you are looking for, but
 > don't know its chapter/section name.

	(Investigating this one is already in my “to do” list.)

[…]

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

> I once looked at the documentation for Org mode, and gave up.  It presented
> doing things I didn't find useful.  I did not see, at the beginning, how
> to use it as markup for manuals.  Perhaps it says that later, but I did not
> get that far.

The documentation for Org doesn't AFAIK explicitly say how to markup a
document for manuals.

But conceptually it is fairly simple: think outline-mode on steroids
(ie. with added primitives for emphasis, hyperlinks, cross reference and
other thing.  It has quite extensive facilities for editing code
examples, because it can use emacs' mode for the language of the example
and also render exported code example with emacs' formatting/colouring
of that language)

And any sub-tree of of an Org document can be exported in a variety of
formats.

> * It is a program.  What we need is a format.

Well... in addition to being an emacs major mode, Org _is_ a format,
supported by at least 4 other programs I can think of offhand (2 vim
modes, and mobile-org for Android and iOS).

> * The program runs only in Emacs.

Even if that was true, why should that be a handicap for writing
documentation for emacs...?

On a side note: As another poster on this thread mentioned, org-mode has
made people use emacs, that otherwise wouldn't have used emacs (they use
emacs to be able to use org-mode as their notebook, timetracker,
organizer etc.).

Re: On being web-friendly and why info must die

[Rasmus]

Note: I don't particularly care about the format of documentation.  Yet, I
do care about wrong information.

Richard Stallman <rms@gnu.org> writes:

> I once looked at the documentation for Org mode, and gave up.  It presented
> doing things I didn't find useful.

This is true for everybody.  There's plenty of features I don't know
anything about, though I semi-regularly contribute to Org.

We are offering two manuals.  The unabridged info manual and the compact
guide, which seems not to be shipped with Emacs, but is available here:

          http://orgmode.org/guide/
          http://orgmode.org/orgguide.pdf

> I did not see, at the beginning, how to use it as markup for manuals.

Perhaps start with the org guide, Chapter 11 Markup for rich export and 12
Exporting.  It's four pages.

Or give me an example paragraph and I will show you how to format it in
Org.

> Perhaps it says that later, but I did not get that far.

As pointed out earlier, Thomas S. Dye has converted the Org-manual to Org.
It's out of date, but may still be illustrative.

      https://raw.githubusercontent.com/tsdye/orgmanual/master/orgmanual.org

> I could consider Org mode as a way of formatting manuals if I saw
> documentation presenting Org mode _as_ a way to format manuals.
> However, it would still have two big drawbacks as a candidate for GNU
> documentation.
>
> * It is a program.  What we need is a format.

This claim is simply wrong.

          (info "(org) Org syntax")
and          
          http://orgmode.org/worg/dev/org-syntax.html

> * The program runs only in Emacs.

Again, your claim is simply false.  The syntax is there and can be support
by anybody.  Other interpreters than org-element.el exists.  For instance,
Github supports a subset of the Org-syntax via org-ruby.  I think vim even
has some support of Org-syntax.

That being said, the export functionality is likely not going to be
re-implemented by other editors.  We can add a program called org-export
that simply exports using Emacs.

> Texinfo is a format and you can use any editor to write that format.

Same with Org.

—Rasmus

-- 
May the Force be with you

RE: On being web-friendly and why info must die

[Drew Adams]

> I frequently point people to particular nodes of our online HTML
> manuals that could answer their question.  The way I do that is
> to find the information in Info, then copy&paste some recognizably
> unique text phrase into a web search engine, check that the
> reference this turns up is the corresponding online version of
> the Info manual and then post the HTML link.

Same here.  Except I don't bother to search the web.  I just go
to the GNU Emacs or Elisp manual on the web (separate HTML page
per node version), search the TOC (first page) for the node name,
and copy the URL of the link to that node.

I do this often.  Instead of just answering questions, it is
most helpful to *point users to the doc*, so they get additional
info and they get the benefit of well thought out presentation.

It is even more helpful to also to tell them how _they_ can find
such doc, by *asking Emacs* directly.

Probably what I should do is write an Emacs command that does
all of that from an Info node: grab the URL to that same manual
node on the web.  But it's so quick to get it manually that I
haven't bothered, so far.

Re: On being web-friendly and why info must die

[David Kastrup]

Drew Adams <drew.adams@oracle.com> writes:

>> I frequently point people to particular nodes of our online HTML
>> manuals that could answer their question.  The way I do that is
>> to find the information in Info, then copy&paste some recognizably
>> unique text phrase into a web search engine, check that the
>> reference this turns up is the corresponding online version of
>> the Info manual and then post the HTML link.
>
> Same here.  Except I don't bother to search the web.  I just go
> to the GNU Emacs or Elisp manual on the web (separate HTML page
> per node version), search the TOC (first page) for the node name,
> and copy the URL of the link to that node.
>
> I do this often.  Instead of just answering questions, it is
> most helpful to *point users to the doc*, so they get additional
> info and they get the benefit of well thought out presentation.
>
> It is even more helpful to also to tell them how _they_ can find
> such doc, by *asking Emacs* directly.
>
> Probably what I should do is write an Emacs command that does
> all of that from an Info node: grab the URL to that same manual
> node on the web.  But it's so quick to get it manually that I
> haven't bothered, so far.

To make that work reliably it might be reasonable to create a Texinfo
command to specify the "canonical" web location and have this converted
into something in Info that the info reader can recognize and interpret.

This should actually even be workable for the standalone Info reader.
Of course it relies on the HTML node name generation being the same as
the Info reader can readily guess.

-- 
David Kastrup

RE: On being web-friendly and why info must die

[Drew Adams]

> > Probably what I should do is write an Emacs command that does
> > all of that from an Info node: grab the URL to that same manual
> > node on the web.  But it's so quick to get it manually that I
> > haven't bothered, so far.
> 
> To make that work reliably it might be reasonable to create a
> Texinfo command to specify the "canonical" web location and have
> this converted into something in Info that the info reader can
> recognize and interpret.
> 
> This should actually even be workable for the standalone Info
> reader.  Of course it relies on the HTML node name generation
> being the same as the Info reader can readily guess.

I would use such an Emacs command, if available.

Would you like to put this in the form of an enhancement request
(`M-x report-emacs-bug')?

If not, I will do so, but for the additional information you
offered I can only point to what you said - I'm no expert on it.

Re: On being web-friendly and why info must die

[David Kastrup]

Drew Adams <drew.adams@oracle.com> writes:

>> > Probably what I should do is write an Emacs command that does
>> > all of that from an Info node: grab the URL to that same manual
>> > node on the web.  But it's so quick to get it manually that I
>> > haven't bothered, so far.
>> 
>> To make that work reliably it might be reasonable to create a
>> Texinfo command to specify the "canonical" web location and have
>> this converted into something in Info that the info reader can
>> recognize and interpret.
>> 
>> This should actually even be workable for the standalone Info
>> reader.  Of course it relies on the HTML node name generation
>> being the same as the Info reader can readily guess.
>
> I would use such an Emacs command, if available.
>
> Would you like to put this in the form of an enhancement request
> (`M-x report-emacs-bug')?

Actually, that's ultimately more like a Texinfo enhancement.  Without
putting this information into the Info file, it would need to get
provided manually for each of the Info manuals you want to be using that
command on.

> If not, I will do so, but for the additional information you offered I
> can only point to what you said - I'm no expert on it.

Well, I can try passing the longterm request to Texinfo and it will take
some time to trickle down into both the sources of people's manuals as
well as into the Info file.  But if Emacs info already provides the
necessary functionality for manually provided information (customization
and prompt, likely), that would already be a benefit.  Even though the
full benefit with Texinfo help will probably take years to materialize
to significant degree.

So feel free to file the Emacs functionality request.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stephen Leake]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> And also because the index-searching commands, without which you are
>> lost in a large manual, don't exist in the Web browsers out there.
>
> This is not at *all* hard to solve.  I have written HTML generators
> that produce index links myself in different contexts.

I'm not sure that "produce index links" and "index-searching commands"
are the same thing; Eli, could you elaborate on what commands you mean?

When I browse info, I use M-/ and/or C-s to search the index listings.

In any case, Texinfo produces index listings in html format;
http://www.gnu.org/software/emacs/manual/html_node/emacs/Key-Index.html#Key-Index

Why reinvent this particular wheel?

>> And finally because Emacs documentation commands have
>> links that go to the respective manual and chapter, but no similar
>> features exist for external browsers.
>
> Generating that kind of link structure from any modern markup is
> almost trivial.  

Sure, it's trivial; so trivial that even Texinfo has it.

>> In sum, switching to a Web browser as the means to read documentation
>> is a regression.
>
> Except to pretty much the entire universe of new developers we need to
> recruit.

We are already meeting that need:

http://www.gnu.org/software/emacs/manual/

I've added that link to ./CONTRIBUTE; where else does it need to be?

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sat, 06 Dec 2014 13:06:19 -0600
> 
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> 
> > Eli Zaretskii <eliz@gnu.org>:
> >> And also because the index-searching commands, without which you are
> >> lost in a large manual, don't exist in the Web browsers out there.
> >
> > This is not at *all* hard to solve.  I have written HTML generators
> > that produce index links myself in different contexts.
> 
> I'm not sure that "produce index links" and "index-searching commands"
> are the same thing

They are not, of course.

> Eli, could you elaborate on what commands you mean?

I meant `i', which is bound to Info-index.

> When I browse info, I use M-/ and/or C-s to search the index listings.

`C-s' searches are much less efficient than `i' in finding stuff in an
Info manual (provided that the manual is well-indexed).

RE: On being web-friendly and why info must die

[Drew Adams]

> > Would you like to put this in the form of an enhancement request
> > (`M-x report-emacs-bug')?
> 
> Actually, that's ultimately more like a Texinfo enhancement.
> Without putting this information into the Info file, it would
> need to get provided manually for each of the Info manuals you
> want to be using that command on.
> 
> > If not, I will do so, but for the additional information you
> > offered I can only point to what you said - I'm no expert on it.
> 
> Well, I can try passing the longterm request to Texinfo and it will
> take some time to trickle down into both the sources of people's
> manuals as well as into the Info file.  But if Emacs info already
> provides the necessary functionality for manually provided
> information (customization and prompt, likely), that would already
> be a benefit.  Even though the full benefit with Texinfo help will
> probably take years to materialize to significant degree.
> 
> So feel free to file the Emacs functionality request.

Done - #19291.
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19291

Re: On being web-friendly and why info must die

[David Kastrup]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> "Eric S. Raymond" <esr@thyrsus.com> writes:
>
>> Eli Zaretskii <eliz@gnu.org>:
>>> And also because the index-searching commands, without which you are
>>> lost in a large manual, don't exist in the Web browsers out there.
>>
>> This is not at *all* hard to solve.  I have written HTML generators
>> that produce index links myself in different contexts.
>
> I'm not sure that "produce index links" and "index-searching commands"
> are the same thing; Eli, could you elaborate on what commands you mean?
>
> When I browse info, I use M-/ and/or C-s to search the index listings.

Seriously?  Try just i for a change.  That's a whole different class of
useful.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Christopher Allan Webber]

David Kastrup writes:

> Christopher Allan Webber <cwebber@dustycloud.org> writes:
>
>> Eric S. Raymond writes:
>>
>>> Karl Fogel <kfogel@red-bean.com>:
>>>> Actually, I think that might be *more* important than the exact choice
>>>> of markup language.  I hope we don't bikeshed.com the choice of markup
>>>> language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.
>>>
>>> Agreed.  I may have given the impression that I'm more attached to
>>> asciidoc per se than I am. It would be my first choice, but a reasoned
>>> case could be made for a couple of the others.
>>
>> Okay, sorry also that I may be responding to that a bit more than
>> anything.  Getting GNU's web documentation improved is an important
>> issue to me, and I really do want this to happen.
>>
>> I do agree that the importance of good web documentation is more
>> important than info support, and if somehow we got tossed into the fork
>> of needing to pick one or the other, I think nice looking web
>> documentation is more important to the long-term health of GNU.
>
> So tell me what you consider wrong with the Texinfo-generated web
> documentation of GNU LilyPond, arbitrary stuff like
> <URL:http://www.lilypond.org/doc/v2.19/Documentation/notation/guitar>.
> What parts of the documentation are "not nice looking" to a degree that
> would be bad for LilyPond's long-term health?

I think it's a big step up from most Texinfo exports, and while I think
it doesn't look as nice as a default sphinx export, it's proof that
Texinfo could be improved to be attractive enough to web users who want
to view the manual.

I think you're upset with me also, but note that I supported a variety
of solutions that kept a Texinfo output *and* got better HTML rendering,
including improving Texinfo HTML theming itself! :)

> I might add that we have several translations of all the web pages and
> manuals which are tightly maintained (and some that are basically in
> some left-behind state, not because of the amount of work Texinfo
> presents since translators do not even need to touch the Texinfo parts
> and, in contrast to some magic-cookie markup system like AsciiDoc are
> not likely to break stuff just by copying things) but rather the amount
> of work a good translation actually is.  Most of our translators (and
> documentation-focused developers) come from a Windows background and/or
> do not contribute significantly to code.

Sure, that's great!

Re: On being web-friendly and why info must die

[David Kastrup]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

> David Kastrup writes:
>
>> Christopher Allan Webber <cwebber@dustycloud.org> writes:
>>
>>> Eric S. Raymond writes:
>>>
>>>> Karl Fogel <kfogel@red-bean.com>:
>>>>> Actually, I think that might be *more* important than the exact choice
>>>>> of markup language.  I hope we don't bikeshed.com the choice of markup
>>>>> language to death.  ${ANYTHING_STANDARD_OR_ORG} is fine by me.
>>>>
>>>> Agreed.  I may have given the impression that I'm more attached to
>>>> asciidoc per se than I am. It would be my first choice, but a reasoned
>>>> case could be made for a couple of the others.
>>>
>>> Okay, sorry also that I may be responding to that a bit more than
>>> anything.  Getting GNU's web documentation improved is an important
>>> issue to me, and I really do want this to happen.
>>>
>>> I do agree that the importance of good web documentation is more
>>> important than info support, and if somehow we got tossed into the fork
>>> of needing to pick one or the other, I think nice looking web
>>> documentation is more important to the long-term health of GNU.
>>
>> So tell me what you consider wrong with the Texinfo-generated web
>> documentation of GNU LilyPond, arbitrary stuff like
>> <URL:http://www.lilypond.org/doc/v2.19/Documentation/notation/guitar>.
>> What parts of the documentation are "not nice looking" to a degree that
>> would be bad for LilyPond's long-term health?
>
> I think it's a big step up from most Texinfo exports, and while I think
> it doesn't look as nice as a default sphinx export, it's proof that
> Texinfo could be improved to be attractive enough to web users who want
> to view the manual.

Well yes, the question is what one can do to make the typical
Texinfo-generated manuals and pages be more palatable.  Of course, the
amount of images in them is up to the manual writers, but it might
become easier to generate them.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> Until there is a documentation viewer available in Elisp that is almost
>> as good as Info-mode while being prettier,
> Does a web browser not qualify?

Notice the "in Elisp" and "prettier".  So far I don't know of any such
thing, web browser or not.


        Stefan

Re: On being web-friendly and why info must die

[Stefan Monnier]

> Anyway, no matter what the reason for not upgrading, in the meantime we're
> stuck with old-technology Texinfo, and this is partly why it might be a good
> idea to think about changing.

FWIW, while I don't hold Texinfo very dearly in my heart, I have some
real problems with labeling it as nothing else than "old-technology".

There are newer tools, of course, but it's not like they're so much
incredibly better that Texinfo is just "old-technology".

CVS is old-technology.  I could even agree that Emacs is old-technology
(with its perks, obviously), but I don't see what so fundamentally
different between Texinfo and newer formats to justify such
a characterization.


        Stefan

Re: On being web-friendly and why info must die

[Jonathan Leech-Pepin]

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

Note: I'm only chiming in with regards to a few limitations of the
org->texinfo
export process.  I wrote the exporter as a way to better understand the new
exporter and came across a few syntax limitations when trying to account
for texinfo syntax.

On 6 December 2014 at 11:43, Rasmus <rasmus@gmx.us> wrote:

[...]


>
> As pointed out earlier, Thomas S. Dye has converted the Org-manual to Org.
> It's out of date, but may still be illustrative.
>
>
> https://raw.githubusercontent.com/tsdye/orgmanual/master/orgmanual.org
>

Org only has a single sort of link specification "[[link][description]]"
where link
can be formatted in multiple ways to provide a method to retrieve the
correct
destination.  This lead to a very limited subset of the @ref/@xref link
types
(which in turn requires the author to assume the burden of ensuring any
"see"
contexts. I made this decision with the assumption that the ox-texinfo
exporter
would be used solely for final export to info format, while other ox-
backends
could be used for HTML, plain text, etc.

Org also does not have any concept of indexes.  Thomas S. Dye took one path
(after discussion of this issue with me while I was working on the
exporter) and
defined macros for each texinfo index type.  An alternate path would be to
define
a link type that behaved similarly (replaced itself on export with an @index
command.  Neither is an ideal solution, the macro solution is probably the
easier
to work with, however implementing indexes in Org would require adding them
to
the syntax and providing a method to parse them when exporting to other
formats
(even if only ignoring them).

> I could consider Org mode as a way of formatting manuals if I saw
> > documentation presenting Org mode _as_ a way to format manuals.
> > However, it would still have two big drawbacks as a candidate for GNU
> > documentation.
> >
> > * It is a program.  What we need is a format.
>
> This claim is simply wrong.
>
>           (info "(org) Org syntax")
> and
>           http://orgmode.org/worg/dev/org-syntax.html
>

If org were to be considered as a source of texinfo/info, determining a
possible syntax for indexes would likely be necessary, but once that
was done, the only real difference would be the lack of the multiple methods
of defining cross references, yet if the only use was to output to info
(leaving
other formats to the org export process [html, ascii]) then this lack could
be
worked around by ensuring the correct context.

Regards,
Jonathan

[-- Attachment #2: Type: text/html, Size: 3621 bytes --]

Re: On being web-friendly and why info must die

[Thien-Thi Nguyen]

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

() Eli Zaretskii <eliz@gnu.org>
() Fri, 05 Dec 2014 22:17:24 +0200

   That would be fine by me, at least.  The back-end can
   certainly be replaced, provided that the replacement
   allows as efficient reading and consulting the
   documentation as the Info format and its Emacs viewer.

   The issue here is mainly about the Texinfo source.  It
   doesn't make sense to switch to another language, exactly
   as it doesn't make sense to switch a C-based project to
   C++ or Java, when all the main developers don't work and
   aren't proficient in these languages.  It's a death blow
   to the project.

Right.  Texinfo for input is fine.  Tell the kids it's like
vitamin E for their mofo anti-aliased twitch-pix hangover...

Anyone interested in hacking IXIN (a proposed "middle-end"
or intermediate form for Texinfo) please search for threads
w/ that word in the texinfo mailing lists a bit (maybe two
or three years) back, and see:

 http://www.gnuvola.org/software/ixin/

for release tarballs.  The unreleased changes are:

 ! [p] Release: 1.8
  * [q] [maint] Reformat NEWS; nfc.
 --
  * [q] [maint] Reformat NEWS; nfc.
  * [q^] No longer distribute {epsf,texinfo}.tex.
  * [q~2] [spec int] Fix typo: Include "(news)" heading.
 +* [p] Release: 1.8

In the context of Emacs, the proof-of-concept IXIN-viewing
program could use a rewrite using shr.el low-level routines,
instead of its own ad-hoc renderer.  Or, just look at the
code as a cautionary tale before running away screaming.  :-D

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: On being web-friendly and why info must die

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> Until there is a documentation viewer available in Elisp that is almost
>>> as good as Info-mode while being prettier,
>> Does a web browser not qualify?
>
> Notice the "in Elisp" and "prettier".  So far I don't know of any such
> thing, web browser or not.

"prettier" for an Info mode replacement it to be taken with a huuuge
grain of salt.  Emacs is an editor, its fonts, foreground, background
are (hopefully) configured for maximum readability.  When jumping back
and forth between work area and documentation, "pretty" takes a hefty
backseat towards readability.  The normal web page appearance, in
contrast, has somewhat different main targets.

So it may well be that a generic browser alone, written in Elisp or not,
does not yet meet the usability offered by Info mode.  Basically what
would be nice is an Info browser that just pulls the same information
from HTML that it pulls from Info files these days but does not
significantly differ except in file format.  And preferably not taking
noticeably longer for parsing and display.  And supporting things like
full-document search for which it needs to have an idea about how to get
the full document.  And, of course, not needing the source on disk.  If
one can just transparently run an Info-like browser on the online
documentation of software, this is a nice boon even though it comes with
the problem of version mismatch between installed software and online
documentation.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Anyway, no matter what the reason for not upgrading, in the meantime we're
>> stuck with old-technology Texinfo, and this is partly why it might be a good
>> idea to think about changing.
>
> FWIW, while I don't hold Texinfo very dearly in my heart, I have some
> real problems with labeling it as nothing else than "old-technology".

The first copyright date in texinfo.tex is from 1985.  TeX originates
from the 70s and still is pervasive for quality batch text typesetting
workflows.  "Old" alone is not bad.  This is the Emacs developer list,
isn't it?

> There are newer tools, of course, but it's not like they're so much
> incredibly better that Texinfo is just "old-technology".

Old wine in new wineskins.

> CVS is old-technology.

And here the inherent limitations are worth ditching it.  Particularly
the lack of convenient private or offline workflows is a real hurdle.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Unfortunately, I don't remember the conclusions of our previous
discussion of replacing Info format.  Maybe someone can look for
it in the archives.

  > In sum, switching to a Web browser as the means to read documentation
  > is a regression.

I agree completely.

Using HTML instead of Info format would be a big improvement, since
HTML is more flexible and can represent a wider range of contents.

However, unless we have an HTML-based Info reader with the same handy
features that the current Info reader has (for instance, the commands
n, p, u, m, i, SPC, search through multiple nodes), it would also be a
big step backward.

Last time I tried browsing HTML generated from Texinfo, it was
inconvenient compared with Info.  It corresponded to the contents of
the Texinfo file, but its navigation was not like Info.

To get the benefit of HTML and avoid the loss, we need

* A good way to represent a manual's info nodes in HTML, including all
their structure such that it can be extracted mechanically.  I suppose
this is not very hard, if you know HTML better than I do, and maybe it
has been done already.  Has it been?

* An HTML-based Info reader (can be done in Emacs) which implements
these commands as well as the usual HTML browsing features.  (Of
course, these commands won't be available to someone using an ordinary
browser to look at the same HTML files, but that is out of our hands.)

You could think of this as a special-purpose browser for web pages
of documenation.

If we succeed in recreating the features of Info in HTML, we would
have no reason to keep using the Info format.  Then we could use other
source formats (which can't generate Info).

Not all GNU packages would have to switch, but individual projects
COULD switch.

Do people want to work on this project for HTML?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > And also because the index-searching commands, without which you are
  > > lost in a large manual, don't exist in the Web browsers out there.

  > This is not at *all* hard to solve.  I have written HTML generators
  > that produce index links myself in different contexts.

With Texinfo, we specify which items to index in each node or place,
with commands such as @cindex and @findex and @vindex.

When you talking about "produce index links", what does that mean
concretely?  What input in asciidoc would control the index?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > And finally because Emacs documentation commands have
  > > links that go to the respective manual and chapter, but no similar
  > > features exist for external browsers.

  > Generating that kind of link structure from any modern markup is
  > almost trivial.

Generating a link structure in the HTML files is the first step needed
for this.  The second step is to write the Emacs commands to visit the
appropriate Info node, using that link structure.

Has that been done?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Because it's ugly, heavyweight, and a barrier to entry.  I know you
  > > do not understand this.

  > It must be hard for you being the only intelligent being in a world of
  > idiots, but it's not like this is a new experience for you.

That would be a great contribution to a book of funny putdowns.
I couldn't help laughing.

But thinking seriously, I think we would be well advised, in this
list, to avoid putting people down, even in funny ways -- especially
when we criticize of what they have said.  We need to make an effort
to avoid personal hostility when we disagree.

You're not the only one this applies to.  Eric too needs to respect
the rest of the people on this list when disagreeing with them.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I once looked at the documentation for Org mode, and gave up.  It presented
  > > doing things I didn't find useful.

  > This is true for everybody.  There's plenty of features I don't know
  > anything about, though I semi-regularly contribute to Org.

I think my statement was misunderstood.

When I started reading the Org mode manual, 
everything I saw at the beginning was uninteresting,
things I had no wish to do.  So I stopped reading it.

  > > I could consider Org mode as a way of formatting manuals if I saw
  > > documentation presenting Org mode _as_ a way to format manuals.
  > > However, it would still have two big drawbacks as a candidate for GNU
  > > documentation.
  > >
  > > * It is a program.  What we need is a format.

  > This claim is simply wrong.

What people have proposed, so far, is to use Org mode.
That is a program that runs in Emacs.

To propose using Org _format_ is a different proposal.
We can consider that.

  > > * The program runs only in Emacs.

  > Again, your claim is simply false.  The syntax is there and can be support
  > by anybody.

Org mode is not a syntax, it is a program written in Emacs Lisp.

		 Other interpreters than org-element.el exists.  For instance,
  > Github supports a subset of the Org-syntax via org-ruby.  I think vim even
  > has some support of Org-syntax.

Interesting.

I will look at the page that describes Org format.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > * The program runs only in Emacs.

  > Even if that was true, why should that be a handicap for writing
  > documentation for emacs...?

GNU documentation standards are not for Emacs alone.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

David Kastrup writes:

 > "prettier" for an Info mode replacement it to be taken with a huuuge
 > grain of salt.  Emacs is an editor, its fonts, foreground, background
 > are (hopefully) configured for maximum readability.

This is a few lines of CSS.

 > So it may well be that a generic browser alone, written in Elisp or not,
 > does not yet meet the usability offered by Info mode.

And this a few score lines of Javascript.  (I'm understating, most
likely, I admit.)

But I haven't yet seen anything like it accompanying common web docs,
which are written to the same level of taste that most "modern" "who
needs a document window when we need to put up 4 10x10 tool palettes
simultaneously" UIs aspire to (eg, GIMP, or a fully decorated Internet
Exploder).

We need a proof of concept at least, and preferably an Emacs-based
browser (I wonder if eww isn't too far from being capable, but I
haven't looked at its code).

Re: On being web-friendly and why info must die

[David Kastrup]

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

> David Kastrup writes:
>
>  > "prettier" for an Info mode replacement it to be taken with a huuuge
>  > grain of salt.  Emacs is an editor, its fonts, foreground, background
>  > are (hopefully) configured for maximum readability.
>
> This is a few lines of CSS.

The problem is that the default HTML output of Texinfo is pretty good in
that respect.  It's awful in the "nice web appearance" category.  Web
pages and Info pages have different requirements.  There are also
structural differences hinging on the different kind of page layout:
you'll use frames for nice navigation/webbing in a browser while using
menus or keyboard shortcuts for an Info browser in order to save the
screen estate for the content.  My web browser is typically running on a
desktop of its own, basically in landscape format, while my Emacs
occupies just below half of a desktop using only 80 columns (which is
about the limit one can usefully read in running text without losing
orientation).

So layout, geometry, and also the color model at least outside of the
bulk text area are different for web browsing and Info browsing.

Which is, by the way, the main problem I have with using eww for about
anything: it just makes a framy wrapping mess of the 80 columns of text
area I give it.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > > And also because the index-searching commands, without which you are
>   > > lost in a large manual, don't exist in the Web browsers out there.
>
>   > This is not at *all* hard to solve.  I have written HTML generators
>   > that produce index links myself in different contexts.
>
> With Texinfo, we specify which items to index in each node or place,
> with commands such as @cindex and @findex and @vindex.
>
> When you talking about "produce index links", what does that mean
> concretely?  What input in asciidoc would control the index?

There are

indexterm: ...

commands for this.  However, they somewhat defeat the basic principle
that AsciiDoc is supposed to be its own plain text output since the
indexing information is not relevant for reading the text.
Consequently, the documentation states that those commands only make
sense if you intend to create DocBook markup, namely go through further
processing (that might, through a2x, even be used for generating
"stripped" plain text).

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> Unfortunately, I don't remember the conclusions of our previous
> discussion of replacing Info format.  Maybe someone can look for
> it in the archives.
>
>   > In sum, switching to a Web browser as the means to read documentation
>   > is a regression.
>
> I agree completely.
>
> Using HTML instead of Info format would be a big improvement, since
> HTML is more flexible and can represent a wider range of contents.
>
> However, unless we have an HTML-based Info reader with the same handy
> features that the current Info reader has (for instance, the commands
> n, p, u, m, i, SPC, search through multiple nodes), it would also be a
> big step backward.

One big advantage of Info is the instantaneous response partly due to
the preformatted content.  At least the parsing should hopefully be
workably fast when relying on libxml2 like eww, to my belief, does.

But we still need to reflow.

-- 
David Kastrup

Info and HTML

[Ivan Shmakov]

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

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

[…]

 > Using HTML instead of Info format would be a big improvement, since
 > HTML is more flexible and can represent a wider range of contents.

 > However, unless we have an HTML-based Info reader with the same handy
 > features that the current Info reader has (for instance, the commands
 > n, p, u,

	These commands are already implemented in EWW.  They use the
	respective @rel attributes produced by Texinfo; for instance:

$ nl -ba < www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html 
…
    40	<p>
    41	Next:&nbsp;<a rel="next" accesskey="n" href="M_002dx.html#M_002dx">M-x</a>,
    42	Previous:&nbsp;<a rel="previous" accesskey="p" href="Basic.html#Basic">Basic</a>,
    43	Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>

	(The eww-up-url command does not currently work due to a typo
	in the EWW code; see the patch MIMEd.)

 > m,

	The menu items in the Texinfo-produced HTML come with @accesskey
	attributes, which are, however, currently ignored by EWW:

    57	<ul class="menu">
    58	<li><a accesskey="1" href="Basic-Minibuffer.html#Basic-Minibuffer">Basic Minibuffer</a>:       Basic usage of the minibuffer. 
    59	<li><a accesskey="2" href="Minibuffer-File.html#Minibuffer-File">Minibuffer File</a>:        Entering file names with the minibuffer. 
    60	<li><a accesskey="3" href="Minibuffer-Edit.html#Minibuffer-Edit">Minibuffer Edit</a>:        How to edit in the minibuffer. 

	Presumably, we can use one another value for the @rel attribute
	(menu-entry or nav-entry, perhaps?) to fill for that role.

 > i,

	This one is somewhat trickier.  First of all, we need a way to
	point the browser to the relevant index page(s).  The <link />
	element would fit this purpose, although again, I know of no
	@rel value currently in use for this purpose.  (At the very
	least, [1, 2] do not seem to mention anything related.)

	Then, on these index pages, we should somehow mark the index
	terms proper, for which we may again use a specific @rel value.
	(Say, rel="index-page" and rel="index-term"?)

[1] http://microformats.org/wiki/existing-rel-values
[2] http://microformats.org/wiki/Special:PrefixIndex/rel

 > SPC,

	This one is already bound to scroll-up-command, but I guess you
	mean that there should be a kind of eww-scroll-up-or-next-page
	command as well?

 > search through multiple nodes), it would also be a big step backward.

	It is certainly possible to walk over the structure pointed by
	the @rel links, but that will require the browser to retrieve
	(and cache) potentially the entire HTML manual.

	My guess is that there generally should be some kind of
	server-side search facility accompanying the manuals, for those
	having limited bandwidth.

[…]

 > To get the benefit of HTML and avoid the loss, we need

 > * A good way to represent a manual's info nodes in HTML, including
 > all their structure such that it can be extracted mechanically.
 > I suppose this is not very hard, if you know HTML better than I do,
 > and maybe it has been done already.  Has it been?

	Unless I forgot something (which is quite likely), the above
	should be it.

 > * An HTML-based Info reader (can be done in Emacs) which implements
 > these commands as well as the usual HTML browsing features.
 > (Of course, these commands won't be available to someone using an
 > ordinary browser to look at the same HTML files, but that is out of
 > our hands.)

 > You could think of this as a special-purpose browser for web pages of
 > documentation.

	Even though I’m hardly a fan of ECMAScript-based solutions, I
	guess we may employ some such solution to allow for easy access
	to the indices at the least.  The other features (or, rather,
	key bindings) are mostly there, thanks to @accesskey.

[…]

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

[-- Attachment #2: Type: text/plain, Size: 284 bytes --]

--- a/lisp/net/eww.el
+++ b/lisp/net/eww.el
@@ -427,7 +427,7 @@ defun eww-handle-link (dom)
 		   ("start" . :start)
 		   ("home" . :home)
 		   ("contents" . :contents)
-		   ("up" . up)))))
+		   ("up" . :up)))))
     (and href
 	 where
 	 (plist-put eww-data (cdr where) href))))

Info and HTML

[Ivan Shmakov]

>>>>> David Kastrup <dak@gnu.org> writes:

[…]

 > My web browser is typically running on a desktop of its own,
 > basically in landscape format, while my Emacs occupies just below
 > half of a desktop using only 80 columns (which is about the limit one
 > can usefully read in running text without losing orientation).

	My preference is to configure Firefox (which serves as my
	secondary browser) to use something close to 80 columns for the
	HTML documents, either.  Whenever feasible, I use CSS overrides
	(via Stylish) to move the sidebars and the likes off to the
	bottom of the page, or to remove them altogether.

 > So layout, geometry, and also the color model at least outside of the
 > bulk text area are different for web browsing and Info browsing.

 > Which is, by the way, the main problem I have with using eww for
 > about anything: it just makes a framy wrapping mess of the 80 columns
 > of text area I give it.

	On the EWW side, there’s that new eww-readable feature which I’m
	yet to try out.

	On the document side, the proper markup has the payload content
	/not/ wrapped in any tables or frames, and has the navigation
	going after it, not before.  That’s, e. g., how modern MediaWiki
	software behaves by default, and so that’s how Wikipedia (and
	the rest of WMF wikis) show up – giving an entirely reasonable
	Web reading experience with EWW, Lynx, etc.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

>>> * The program runs only in Emacs.

>> Even if that was true, why should that be a handicap for writing
>> documentation for emacs...?

> GNU documentation standards are not for Emacs alone.

Well, as was stated in the snipped part of the quoted message, and as
has been stated in other messages in the thread: it isn't true.

Org is a text based markup that can be edited in any text editor, with
approximately the same readability as markdown.

It's just that emacs has (IMO) the best facilities for navigating and
editing the format.

Re: On being web-friendly and why info must die

[Ivan Shmakov]

>>>>> Steinar Bang <sb@dod.no> writes:
>>>>> Richard Stallman <rms@gnu.org>:

 >>>> * The program runs only in Emacs.

 >>> Even if that was true, why should that be a handicap for writing
 >>> documentation for emacs...?

 >> GNU documentation standards are not for Emacs alone.

 > Well, as was stated in the snipped part of the quoted message, and as
 > has been stated in other messages in the thread: it isn't true.

 > Org is a text based markup that can be edited in any text editor,
 > with approximately the same readability as markdown.

 > It's just that emacs has (IMO) the best facilities for navigating and
 > editing the format.

	Is it also possible to generate HTML from Org without Emacs?
	If so, what are the respective tools?

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Steinar Bang]

> When I started reading the Org mode manual, 
> everything I saw at the beginning was uninteresting,
> things I had no wish to do.  So I stopped reading it.

Here is an example-based walkthrough of a subset of the format:
 http://steinar.bang.priv.no/2012/05/02/using-org-mode/

Basic document structure of a document is shown (the "memo" part), but I
didn't cover emphasis formatting, web links and cross references or
tables, all of which are essential for a Texinfo replacement.

Though it shows a C source code example.

The "memo" subtree can be exported as a document, in a variety of
formats ('C-c C-e' when standing on the node, and then browse the
alternatives)

(it might be of slight interest that the blog article itself was written
in Org, as were the rest of the articles on that blog)

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Ivan Shmakov <ivan@siamics.net>:

> Is it also possible to generate HTML from Org without Emacs?
> If so, what are the respective tools?

I don't offhand know of any such tools.  I know github renders org as
HTML on the fly, using something called org-ruby
 https://github.com/bdewey/org-ruby

(I took a quick look at the makeinfo source to see how much work it
would be to replace the parser there, and concluded that this would be
quite a bit of work...)

This page has Org parsers for pico-lisp, common lisp, nodejs, python
(seems to be dead, a different python project is called NEO these days),
ruby, and js (presumably browser js).
 http://orgmode.org/worg/org-tools/

Hm... http://nakkaya.com/ listed on the org-tools page above, generates
web sites from org files, using Clojure.

Re: On being web-friendly and why info must die

[Rasmus]

Hi,

Richard Stallman <rms@gnu.org> writes:

> When I started reading the Org mode manual, 
> everything I saw at the beginning was uninteresting,
> things I had no wish to do.  So I stopped reading it.

If you ever desire to give it a second try, I would then suggest that you
take a look at the compact guide that I referred to in my previous email.

> To propose using Org _format_ is a different proposal.
> We can consider that.
> [...] 
> Org mode is not a syntax, it is a program written in Emacs Lisp.

People who have suggested Org have the Org format/syntax in mind.  These
people would likely work with org-mode: the principal "editor" of the Org
format.

Org-mode is the principal editor of the Org-format, if you want.  As other
have suggested, the format is used outside of Org (a search on Github for
"readme.org" gives approx. 8300 results; of course many of these may be
duplicates (forked repositories)).

>   > Other interpreters than org-element.el exists.  For instance, Github
>   > supports a subset of the Org-syntax via org-ruby.  I think vim even
>   > has some support of Org-syntax.
>
> Interesting.
>
> I will look at the page that describes Org format.

It's terse and meant to document the syntax for parsing purposed.
Nonetheless it's an intriguing read.  

For a quick introduction to usage of the syntax and the org-mode, the
org-guide may be preferable.

—Rasmus

-- 
And I faced endless streams of vendor-approved Ikea furniture. . .

Re: On being web-friendly and why info must die

[Rasmus]

Hi,

Ivan Shmakov <ivan@siamics.net> writes:

> 	Is it also possible to generate HTML from Org without Emacs?
> 	If so, what are the respective tools?

Well, ox-html depends at the very least on ox.el, ox-html.el and
org-element.el which is some probably some 15.000 lines of code.  So
probably not.

But I don't understand why this would be an issue.  Emacs runs on every
platform and we can make an auxiliary command-line tool that uses
emacs --batch for making export convenient for make and people who do not
want to use Emacs.  An example of such tools already exists as third-party, e.g. orgmk

     https://github.com/fniessen/orgmk
     
BTW: the Org-manual is a texi document, and I find the online
representation very pleasant and modern:

     http://orgmode.org/org.html

—Rasmus

-- 
Not everything that goes around comes back around, you know

Re: On being web-friendly and why info must die

[Stephen Leake]

David Kastrup <dak@gnu.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>>> > Probably what I should do is write an Emacs command that does
>>> > all of that from an Info node: grab the URL to that same manual
>>> > node on the web.  But it's so quick to get it manually that I
>>> > haven't bothered, so far.
>>> 
>>> To make that work reliably it might be reasonable to create a
>>> Texinfo command to specify the "canonical" web location and have
>>> this converted into something in Info that the info reader can
>>> recognize and interpret.
>>> 
>>> This should actually even be workable for the standalone Info
>>> reader.  Of course it relies on the HTML node name generation
>>> being the same as the Info reader can readily guess.
>>
>> I would use such an Emacs command, if available.
>>
>> Would you like to put this in the form of an enhancement request
>> (`M-x report-emacs-bug')?
>
> Actually, that's ultimately more like a Texinfo enhancement.  Without
> putting this information into the Info file, it would need to get
> provided manually for each of the Info manuals you want to be using that
> command on.

Right. But as a near-term workaround, there is a fixed url for all of
the Gnu/Emacs manuals, so and external command for just those would help
a lot.

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Stephen Leake]

David Kastrup <dak@gnu.org> writes:

> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> "Eric S. Raymond" <esr@thyrsus.com> writes:
>>
>>> Eli Zaretskii <eliz@gnu.org>:
>>>> And also because the index-searching commands, without which you are
>>>> lost in a large manual, don't exist in the Web browsers out there.
>>>
>>> This is not at *all* hard to solve.  I have written HTML generators
>>> that produce index links myself in different contexts.
>>
>> I'm not sure that "produce index links" and "index-searching commands"
>> are the same thing; Eli, could you elaborate on what commands you mean?
>>
>> When I browse info, I use M-/ and/or C-s to search the index listings.
>
> Seriously?  Try just i for a change.  That's a whole different class of
> useful.

Indeed it is.

There are only a million key bindings in Emacs; I'm continually
surprised to learn that I don't know them all yet :).

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Is there software to generate TeX input from Org format?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Alternative input formats

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

If we develop software to browse HTML manuals made by Texifo with all
the good features of info, then we can drop use of Info format.

Then there will be no reason to insist on one particular source format
for manuals for GNU packages.  We could allow any source markup format
that can generate the three kinds of output we want:

* Nicely formatted PS or PDF.  (Ideally, passed through TeX.)

* HTML used like Info version 2.

* Plain ASCII.

If Org format can do these jobs, they it would be one of the
acceptable source markup formats.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Alexis]

Richard Stallman writes:

> Is there software to generate TeX input from Org format?

Do you mean, outside of `org-mode' itself? If so, i don't
know. Otherwise, yes, many people write academic papers, presentations
etc. in Org format, then export to LaTeX; cf.

http://orgmode.org/manual/Embedded-LaTeX.html#Embedded-LaTeX

and

http://orgmode.org/manual/LaTeX-and-PDF-export.html#LaTeX-and-PDF-export



Alexis.

Re: On being web-friendly and why info must die

[Paul Eggert]

Stefan Monnier wrote:
>> Anyway, no matter what the reason for not upgrading, in the meantime we're
>> >stuck with old-technology Texinfo, and this is partly why it might be a good
>> >idea to think about changing.
> FWIW, while I don't hold Texinfo very dearly in my heart, I have some
> real problems with labeling it as nothing else than "old-technology".

By "old-technology Texinfo" I merely meant Texinfo 4 and earlier; I didn't mean 
to imply that Texinfo is inherently old-technology.

Texinfo 5 uses newer technology and supports Unicode characters etc., but is 
wwwwaaaaayyyyyyy toooo ssllloooooowwww, so slow that it routinely hinders me 
(and no doubt others) from improving the Emacs documentation.  Although I and 
others have reported the performance bug to the Texinfo maintainers, they've 
made it clear that the problem is not likely to be fixed any time soon.  So, 
right now we're stuck between the rock of Texinfo 4 and the hard place of 
Texinfo 5, and this is an argument for switching to some other format.

Re: Alternative input formats

[Rasmus]

Richard Stallman <rms@gnu.org> writes:

> If we develop software to browse HTML manuals made by Texifo with all
> the good features of info, then we can drop use of Info format.

See below.

> Then there will be no reason to insist on one particular source format
> for manuals for GNU packages.  We could allow any source markup format
> that can generate the three kinds of output we want:

Seems reasonable.

For Org:

> * Nicely formatted PS or PDF.  (Ideally, passed through TeX.)

ox-latex.el.  Note that the previously suggested asciidocs features
experimental LaTeX support cf its manual...

> * HTML used like Info version 2.

ox-html.el or ox-texinfo.el and then convert texi-file to html.

> * Plain ASCII.

ox-ascii.el.  It supports utf8, ascii and latin1 out of the box.

> If Org format can do these jobs, they it would be one of the
> acceptable source markup formats.

Fundamentally, I'm still uncertain about the desired goal of replacing
Info.  If we want to support a "simpler" format, Org may fit the bill.
But since Org exports to Info, why this need of replacing the
Info-browser?  Is it too steep to require Info-files as well?

—Rasmus

-- 
M-mm-mmm-mmmm bacon!

Re: On being web-friendly and why info must die

[Stefan Monnier]

> Texinfo 5 uses newer technology and supports Unicode characters etc., but is
> wwwwaaaaayyyyyyy toooo ssllloooooowwww, so slow that it routinely hinders me
> (and no doubt others) from improving the Emacs documentation.

Indeed the slowdown (factor 100 IIRC last time I measured it) is
a serious problem.

> Although I and others have reported the performance bug to the Texinfo
> maintainers, they've made it clear that the problem is not likely to be
> fixed any time soon.

I think I understand why they don't want to fix the processing speed.
But we should still push them to provide workarounds.  "Separate
compilation" would solve this problem: the whole Elisp manual is
enormous, but if we could update the manual by only processing those
files which have changed, then I think the speed of Texinfo-5's
processing would become acceptable.


        Stefan

Re: Alternative input formats

[Stefan Monnier]

> If we develop software to browse HTML manuals made by Texifo with all
> the good features of info, then we can drop use of Info format.

You can definitely get "as good as Info" (or close enough) when browsing
HTML within a browser like Iceweasel, although it will almost invariably
be a lot more sluggish.

But getting this within Emacs, for "full HTML" sounds pretty difficult,
both because of limitations of Emacs's redisplay code, and because "full
HTML" nowadays goes much beyond the SGML markup language and includes
Javascript along with a large runtime library.

So it would necessarily have to be limited to a specific subset of HTML.


        Stefan

Re: Alternative input formats

[Stephen J. Turnbull]

Stefan Monnier writes:

 > But getting this within Emacs, for "full HTML" sounds pretty difficult,
 > both because of limitations of Emacs's redisplay code, and because "full
 > HTML" nowadays goes much beyond the SGML markup language and includes
 > Javascript along with a large runtime library.
 > 
 > So it would necessarily have to be limited to a specific subset of
 > HTML.

How about calling the subset "InfoML, the Info-featured HTML subset"?
It would also need to spec a CSS subset, I think (see below).

I don't think anybody has asked for "full HTML" (and definitely not
"full HTML5", although some HTML5 features might be nice).  Certainly
the necessary navigation features are easy to implement in Emacs Lisp.
The Emacs Lisp InfoML browser can provide them natively, and ignore
the Ecmascript functions that conventional browsers would probably use
to support navigation.

Other than that we need faces, and I would suggest prohibiting EM (and
I!) and STRONG (ditto B!) elements in favor of semantic markup on DIV
and SPAN elements ('class="nextNode"' and the like).  Then the
conventional browsers would get appropriate CSS.  Again, the Emacs
Lisp InfoML browser can ignore the CSS, at least at first.

And links, but Emacs already knows how to do that.

It's not going to require new features from Emacs, but it's not done
yet, and there does need to be a spec for the subset.  And the
Ecmascript and CSS for conventional browsers would also need to be
written.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Sun, 07 Dec 2014 17:30:25 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: Eli Zaretskii <eliz@gnu.org>, esr@thyrsus.com, emacs-devel@gnu.org
> 
> right now we're stuck between the rock of Texinfo 4 and the hard place of 
> Texinfo 5, and this is an argument for switching to some other format.

You should consider the "who will write the documentation" issue as
part of the decision whether to switch.

Re: Alternative input formats

[Ivan Shmakov]

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

[…]

 > I don't think anybody has asked for "full HTML" (and definitely not
 > "full HTML5", although some HTML5 features might be nice).

	I see no outright issues with implementing support for the
	majority of elements and attributes HTML5 defines, – at least
	those unrelated to CSS, ECMAScript, and videos.

	Fortunately, HTML5 makes little effort to specify how a
	conforming browser should display any particular element or
	document, – it instead delegates that to CSS.  Hence, we may
	very well improve EWW for a decent HTML5 conformance, leaving
	CSS conformance aside.

 > Certainly the necessary navigation features are easy to implement in
 > Emacs Lisp.  The Emacs Lisp InfoML browser can provide them natively,
 > and ignore the Ecmascript functions that conventional browsers would
 > probably use to support navigation.

	Seconded.

 > Other than that we need faces, and I would suggest prohibiting EM
 > (and I!) and STRONG (ditto B!) elements in favor of semantic markup
 > on DIV and SPAN elements ('class="nextNode"' and the like).

	I’m unsure if I understand; per the HTML5 specification, <em />
	and <strong /> are /already/ “semantic markup,” – as well as
	<i /> and <b /> (which are redefined to that effect.)  Consider
	the excerpts from [1] below.

	I hope you don’t suggest we use, say, <span class="emphasis" />
	instead of plain <em />?

[1] http://www.w3.org/TR/html5/text-level-semantics.html

[…]

4.5.2 The em element

The em element represents stress emphasis of its contents.

4.5.3 The strong element

The strong element represents strong importance, seriousness, or urgency
for its contents.

4.5.17 The i element

The i element represents a span of text in an alternate voice or mood,
or otherwise offset from the normal prose in a manner indicating a
different quality of text, such as a taxonomic designation, a technical
term, an idiomatic phrase from another language, transliteration, a
thought, or a ship name in Western texts.

4.5.18 The b element

The b element represents a span of text to which attention is being
drawn for utilitarian purposes without conveying any extra importance
and with no implication of an alternate voice or mood, such as key words
in a document abstract, product names in a review, actionable words in
interactive text-driven software, or an article lede.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

> Is there software to generate TeX input from Org format?

Yes, there is.

Emacs org-mode can export the entire document, or a subtree of the
document, to both LaTeX and TeXinfo.

Re: On being web-friendly and why info must die

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
>> Date: Fri, 05 Dec 2014 14:01:00 +0000
>> Cc: emacs-devel@gnu.org
>> 
>> I am almost certainly not the person to do this, but I am willing to
>> contribute to the documentation. I write well, or at least I think I do
>> but then who doesn't.
>
> Thanks for the offer.  Please consider working on the documentation
> changes required by the new features mentioned in NEWS.  Every entry
> there that isn't marked with either "+++" or "---" needs a doc update.


I shall investigate. I guess this means I would need to learn texinfo!

Phil

Re: Alternative input formats

[joakim]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> If we develop software to browse HTML manuals made by Texifo with all
>> the good features of info, then we can drop use of Info format.
>
> You can definitely get "as good as Info" (or close enough) when browsing
> HTML within a browser like Iceweasel, although it will almost invariably
> be a lot more sluggish.
>
> But getting this within Emacs, for "full HTML" sounds pretty difficult,
> both because of limitations of Emacs's redisplay code, and because "full
> HTML" nowadays goes much beyond the SGML markup language and includes
> Javascript along with a large runtime library.
>
> So it would necessarily have to be limited to a specific subset of HTML.

Just a reminder about the xwidget branch.

>
>
>         Stefan
>

-- 
Joakim Verona

Re: On being web-friendly and why info must die

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Fri, 5 Dec 2014 14:36:43 -0500
>> From: "Eric S. Raymond" <esr@thyrsus.com>
>> Cc: Rüdiger Sonderfeld <ruediger@c-plusplus.de>,
>> 	emacs-devel@gnu.org
>> 
>> > But a lot of this is cosmetic.  We could improve Texinfo to look much
>> > better probably (and that would positively affect a lot of existing GNU
>> > projects).
>> 
>> But it would still be Texinfo, still be an essentially pointless
>> barrier to learning how to contribute.
>
> Nonsense.  What evidence do you have to back that up?

I think it is intrinsically hard to get evidence for why people do NOT
do something. The best I can do is given personal experience.

I did try and learn texinfo once, but stopped. I could never understand
why it had all the menu stuff in it. Running occur gives me this...


4 matches for "List Processing" in buffer: emacs-lisp-intro.texi
    238:* List Processing::             What is Lisp?
    277:List Processing
    998:@node List Processing
    999:@chapter List Processing

Can it really be the case that the same text appears four times? If I
use latex, I just do "\tableofcontents". Or asciidoc. Texinfo seems to
totally conflate document structure and navigation. I just want to
maintain one of these. Texinfo seems to have all the complexity of latex
with less of the advantages. This is how it seemed to be 15 years ago
when I last looked at texinfo, although 15 years ago, I couldn't see an
alternative.

I have used asciidoc. I learned it for a trivial reason -- it has a nice
blogposting XML-RPC tool associated with it. I've used it for other
things since; I write my lecture slides with it. I also contributed some
code to it (I added some of the support for doing slides IIRC). I also
use org (for TODO notes). And LaTeX. And markdown.

Everything that has been said about the indexing in info is entirely
true. Like everyone else, I navigate extensively with indexing;
although, perhaps this is partly because info doesn't do inline
hyperlinks. Imagine:

    "At any time, one window is the "selected window". On a graphical
    display, the selected window shows a more prominent cursor (usually
    solid and blinking)

like:

    "At any time, one window (see Windows) is the "selected window" (see
    selected-window). On a graphical display (see Graphical Display),
    the selected window (see selected-window) shows a more prominent
    cursor (set Cursor) (usually solid and blinking (see set-cursor-color)"

Unreadable right? Now, if info used wiki style hyperlinks, maybe I would
never use the index explicitly. Or more rarely.

As it stands, though, if I were starting a new project, I cannot see
why I would start off with texinfo. I can't see what it's key feature
is. 

Does this make it worth changing from? That's a much harder question.

Phil

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
>>> Date: Fri, 05 Dec 2014 14:01:00 +0000
>>> Cc: emacs-devel@gnu.org
>>> 
>>> I am almost certainly not the person to do this, but I am willing to
>>> contribute to the documentation. I write well, or at least I think I do
>>> but then who doesn't.
>>
>> Thanks for the offer.  Please consider working on the documentation
>> changes required by the new features mentioned in NEWS.  Every entry
>> there that isn't marked with either "+++" or "---" needs a doc update.
>
>
> I shall investigate. I guess this means I would need to learn texinfo!

Not really.  Adding documentation, if we are not talking about writing a
whole new document, basically means going by analogy with the material
you are augmenting and looking what it uses.  With Texinfo that's quite
easier than with AsciiDoc since you can clearly see what is relevant
Texinfo code and what is just incidental ASCII art.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Filipp Gunbin]

On 05/12/2014 07:35 -0500, Eric S. Raymond wrote:

> Several recent posts in the metaproblem threads have had the common
> theme that Emacs's web resources are weak, scattered, and unfocused.
> In particular, guidance for new developers that should be public,
> prominent and webbed is buried in obscure text files deep in the Emacs 
> source distribution.
>
> I think the major reason this has not happened is because the Emacs
> development culture is still largely stuck in a pre-Web mindset.
> There are a number of historically contingent reasons for this, but
> enumerating them is not really important.  What matters is recognizing
> that this is a problem and fixing it.

You write about a "pre-Web mindset".  But what is a proper "Web-midset",
then?  I see my colleagues googling nearly everything while they can
access most of it locally (like Javadocs - I'm a Java developer).  Is
that we should be prepared for?  I don't want to.

It's so nice to have a solid program like Emacs independent of whatever
things happening on the Internet, and a documentation system (Info)
too.  Why not improve things instead of throwing them away?

Although I like my web browsers of choice (emacs-w3m and Safari for
sites which need javascript), I'd be happy not to use the web browser at
all while at work.

And this largely reminds me the discussion "make CUA the default because
it will attract new users familiar with Word/Notepad/etc.).

Just my opinion.

Filipp

Re: On being web-friendly and why info must die

[Tom]

Filipp Gunbin <fgunbin <at> fastmail.fm> writes:
> 
> You write about a "pre-Web mindset".  But what is a proper "Web-midset",
> then?  I see my colleagues googling nearly everything while they can
> access most of it locally (like Javadocs - I'm a Java developer). 

I often use google to lookup something which I also have locally,because
usually it is much faster. Even for emacs docs. Google does word stemming
and alternatives, so if you search for something related "modification"
then google also finds matches with "changing", "altering", etc.

So if you don't know the exact wording of what you are looking for
then google is faster most of the time.

Info, for example, cannot do this, so it is faster only if you already
know what you are looking for, you know the exact term, etc. In other
cases, when looking up something new and unfamiliar in the docs, using
Google is usually more efficient.

> And this largely reminds me the discussion "make CUA the default because
> it will attract new users familiar with Word/Notepad/etc.).

It's not about attracting, it's about eliminating arbitrary barriers
of entry. When popular systems use CUA keys then it is a barrier for
new users if they have to relearn these keys just for emacs. For this
reason it would make sense to make CUA keys the default, and provide
a compatibility switch for Emacs old timers who are used to the current
bindings.

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Tom <adatgyujto@gmail.com>:
> I often use google to lookup something which I also have locally,because
> usually it is much faster. Even for emacs docs. Google does word stemming
> and alternatives, so if you search for something related "modification"
> then google also finds matches with "changing", "altering", etc.
> 
> So if you don't know the exact wording of what you are looking for
> then google is faster most of the time.
> 
> Info, for example, cannot do this, so it is faster only if you already
> know what you are looking for, you know the exact term, etc. In other
> cases, when looking up something new and unfamiliar in the docs, using
> Google is usually more efficient.

When I speak of info as being a documentation ghetto, this is one of the
main issues I have in mind.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Alternative input formats

[Stefan Monnier]

> Just a reminder about the xwidget branch.

I haven't forgotten it, don't worry.

It eases the use of a browser by integrating it into Emacs's window
and buffer management, but that doesn't affect my arguments at all
(which don't have to do with switching to another window).


        Stefan

Re: Alternative input formats

[Stefan Monnier]

> I don't think anybody has asked for "full HTML" (and definitely not
> "full HTML5", although some HTML5 features might be nice).

Not exactly, but when Richard said:

  Then there will be no reason to insist on one particular source format
  for manuals for GNU packages.  We could allow any source markup format
  that can generate the three kinds of output we want:
  
  * Nicely formatted PS or PDF.  (Ideally, passed through TeX.)
  
  * HTML used like Info version 2.

There's obviously the problem that until we actually define our "InfoML"
and promote it, the likelyhood that existing document publishing systems
(like Org, RST, AsciiDoc, MarkDown, DocBook, Sphynx, younameit) happen
to fall within this subset seems rather small.

But, yes I'm all for an InfoML, provided we have an infoml.el that's
able to render it fast enough.  And who knows, maybe we can design it to
be "the union of the output of those existing systems".


        Stefan

Re: On being web-friendly and why info must die

[Stefan Monnier]

> For this reason it would make sense to make CUA keys the default, and
> provide a compatibility switch for Emacs old timers who are used to
> the current bindings.

cua-mode is a clever and reasonably clean hack, but
a hack nevertheless.  So enabling it by default is not really an option.

And note that under Mac OS X, there's no need for it, since Mac OS
X uses another modifier than "control" for those C-x C-c C-v.

I'm not opposed to a long term plan to possibly change C-x, C-c, and
C-v.  But that will require fairly extensive changes, mostly such that
major/minor mode key bindings don't specify full key-sequences but
"relative" sequences along with a base prefix which would then depend on
the user's config.  Maybe something like (new-define-key map
major-mode-prefix [?\C-f] #'foo).  I think such changes could be
generally beneficial (e.g. for things like evil-mode, god-mode, ...),
but someone needs to sit down, and experiment a bit with various designs
to see what would work best in terms of convenience and reliability for
cua, evil, normal use, user customization, and major/minor mode writers.


        Stefan

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Cc: <esr@thyrsus.com>,  <cwebber@dustycloud.org>,  <ruediger@c-plusplus.de>,  <emacs-devel@gnu.org>
> Date: Mon, 08 Dec 2014 12:33:38 +0000
> 
> Eli Zaretskii <address@hidden> writes:
> 
> >> > But a lot of this is cosmetic.  We could improve Texinfo to look much
> >> > better probably (and that would positively affect a lot of existing GNU
> >> > projects).
> >> 
> >> But it would still be Texinfo, still be an essentially pointless
> >> barrier to learning how to contribute.
> >
> > Nonsense.  What evidence do you have to back that up?
> 
> I think it is intrinsically hard to get evidence for why people do NOT
> do something.

What I had in mind was some evidence, even anecdotal one, that people
considered contributing a chunk of docs, but decided against that
because of Texinfo.

> I did try and learn texinfo once, but stopped. I could never understand
> why it had all the menu stuff in it. Running occur gives me this...
> 
> 4 matches for "List Processing" in buffer: emacs-lisp-intro.texi
>     238:* List Processing::             What is Lisp?
>     277:List Processing
>     998:@node List Processing
>     999:@chapter List Processing
> 
> Can it really be the case that the same text appears four times?

Yes.

> If I use latex, I just do "\tableofcontents".

I think you are misinterpreting what you see.

The first and the second "List Processing" hits will be produced
automatically by a suitable command of Texinfo mode -- that's the
moral equivalent of your "\tableofcontents".  The 4th one could be a
different string (there's no requirement that a node and its
chapter/section have the same name, and more often than not they
don't), but the author decided to use the same text for both in this
case.  The 3rd one is the only one you need to write by hand.

> Texinfo seems to totally conflate document structure and
> navigation. I just want to maintain one of these.

Not sure what you mean by that, please clarify.  A Texinfo document's
structure is a graph of nodes, each node is a
chapter/section/subsection.  (Usually, the graph is actually a tree,
but that's not a requirement, and at least one popular manual I know
of does not present a tree.)

You can navigate a Texinfo document in any way you want, either via
next/prev/up/down links or any other way.  Following the links takes
you in the same order as you'd read a book, should the document be
printed.

> Texinfo seems to have all the complexity of latex with less of the
> advantages.

The advantage is that it is simpler and easier to learn.  Of course,
if you are already a TeX/LaTeX user, this is not a real advantage, but
it is definitely an advantage when you ask code developers, which
mostly don't use LaTeX, to provide documentation for their code.

> Everything that has been said about the indexing in info is entirely
> true. Like everyone else, I navigate extensively with indexing;
> although, perhaps this is partly because info doesn't do inline
> hyperlinks. Imagine:
> 
>     "At any time, one window is the "selected window". On a graphical
>     display, the selected window shows a more prominent cursor (usually
>     solid and blinking)
> 
> like:
> 
>     "At any time, one window (see Windows) is the "selected window" (see
>     selected-window). On a graphical display (see Graphical Display),
>     the selected window (see selected-window) shows a more prominent
>     cursor (set Cursor) (usually solid and blinking (see set-cursor-color)"
>
> Unreadable right? Now, if info used wiki style hyperlinks, maybe I would
> never use the index explicitly.

What you show above aren't index links, they are direct hyperlinks to
other places in text.  Indexing is not visible in the formatted
document (except in the Index node, which is auto-generated), only in
the Texinfo source.

And Info does support such "inline hyperlinks".  Here's an example (in
Texinfo; you need to format it and view in Emacs to see the results):

    "At any time, one @ref{Windows, window} is the
    "@ref{selected-window, selected window}". On a @ref{Graphical
    Display, graphical display}, the selected window shows a more
    prominent @ref{Cursor, cursor} (usually solid and blinking,
    @pxref{set-cursor-color}).
  
(The node names are not visible when you read the Info document in
Emacs, so only the hyperlinks remain.)  Okay?

> As it stands, though, if I were starting a new project, I cannot see
> why I would start off with texinfo.

We are not starting a new project; that would be a whole different
ball game.

> Does this make it worth changing from? That's a much harder question.

Well, that's the question discussed here.  Texinfo is well known to
people who work on Emacs documentation, and it has excellent support
in Emacs (Texinfo mode) that alleviates many aspects of Texinfo people
consider to be disadvantages.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Tom <adatgyujto@gmail.com>
> Date: Mon, 8 Dec 2014 14:21:52 +0000 (UTC)
> 
> So if you don't know the exact wording of what you are looking for
> then google is faster most of the time.
> 
> Info, for example, cannot do this, so it is faster only if you already
> know what you are looking for, you know the exact term, etc. In other
> cases, when looking up something new and unfamiliar in the docs, using
> Google is usually more efficient.

Did you know about "M-x info-apropos"?

Granted, that won't find the latest statement by President Obama or a
review of some movie.  Info is a system for consulting software
documentation, so don't expect it to find anything that isn't in some
manual.  But it does have many useful features for looking up things
in the software docs, e.g. see info-look.el.

By contrast, when you google for software docs, you can never know if
the hit you get is up to date or not.  To find that out, you need
quite a lot of additional research, which all but makes up for the
seemingly instant access and wealth of resources.

So before you dismiss Texinfo, give it a chance and study it,
especially its seldom used and little-known features.  If nothing
else, you will have your horizons widened and your payload enriched by
the ideas you see in action.

> > And this largely reminds me the discussion "make CUA the default because
> > it will attract new users familiar with Word/Notepad/etc.).
> 
> It's not about attracting, it's about eliminating arbitrary barriers
> of entry. When popular systems use CUA keys then it is a barrier for
> new users if they have to relearn these keys just for emacs.

What is it with you young people that you are so afraid of "barriers"?
Did someone sell you a fairy tail that there are no barriers in life,
except in Emacs and Texinfo?  If you cannot negotiate these
ridiculously low "barriers", how will you ever succeed in your life
out there?

Re: On being web-friendly and why info must die

[Ted Zlatanov]

On Mon, 08 Dec 2014 18:08:26 +0200 Eli Zaretskii <eliz@gnu.org> wrote: 

EZ> What I had in mind was some evidence, even anecdotal one, that people
EZ> considered contributing a chunk of docs, but decided against that
EZ> because of Texinfo.

It's always been a nasty hurdle for me, discouraging me from writing new
stuff. I can never remember the syntax (I deal with Markdown and other
formats all day, and texinfo gets pushed out).  I also hate having to
list section names twice and the index and all the other nonsense.

FWIW, org-mode is all right but Yet Another Format. I think it wouldn't
be an improvement over texinfo for user adoption. Asciidoc, Docutils, or
Markdown seem much better if we want to make contributions easy.

Ted

Re: On being web-friendly and why info must die

[Filipp Gunbin]

On 08/12/2014 14:21 +0000, Tom wrote:

> Filipp Gunbin writes:
>> 
>> You write about a "pre-Web mindset".  But what is a proper "Web-midset",
>> then?  I see my colleagues googling nearly everything while they can
>> access most of it locally (like Javadocs - I'm a Java developer). 
>
> I often use google to lookup something which I also have locally,because
> usually it is much faster. Even for emacs docs. Google does word stemming
> and alternatives, so if you search for something related "modification"
> then google also finds matches with "changing", "altering", etc.
>
> So if you don't know the exact wording of what you are looking for
> then google is faster most of the time.
>
> Info, for example, cannot do this, so it is faster only if you already
> know what you are looking for, you know the exact term, etc. In other
> cases, when looking up something new and unfamiliar in the docs, using
> Google is usually more efficient.

But why not actually _know_ what you're looking for?  That's why I
prefer navigation over search and look at the TOC first before opening
some node.  This way you get the information in context and it helps to
better understand the topic in the long term, but of course slows down
the immediate access time.  But for that we have `describe-key',
`describe-function' etc.

Filipp

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Mon, 08 Dec 2014 11:29:37 -0500
> 
> On Mon, 08 Dec 2014 18:08:26 +0200 Eli Zaretskii <eliz@gnu.org> wrote: 
> 
> EZ> What I had in mind was some evidence, even anecdotal one, that people
> EZ> considered contributing a chunk of docs, but decided against that
> EZ> because of Texinfo.
> 
> It's always been a nasty hurdle for me, discouraging me from writing new
> stuff. I can never remember the syntax (I deal with Markdown and other
> formats all day, and texinfo gets pushed out).

(Some of) the syntax gets taken care of by the various Texinfo mode
commands.  We could also add items to the menu, if that's useful.

> I also hate having to list section names twice

You don't need to.

> and the index and all the other nonsense.

Indexing is part of the real effort -- it's a human activity for which
there's no automated replacement.  Like writing the text itself --
there's no alternative to doing that yourself, in any documentation
system.

But I will offer you a deal: write plain ASCII, and I will add
markup.  Deal?

Re: On being web-friendly and why info must die

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> For this reason it would make sense to make CUA keys the default, and
>> provide a compatibility switch for Emacs old timers who are used to
>> the current bindings.
>
> cua-mode is a clever and reasonably clean hack, but
> a hack nevertheless.  So enabling it by default is not really an option.
>
> And note that under Mac OS X, there's no need for it, since Mac OS
> X uses another modifier than "control" for those C-x C-c C-v.
>
> I'm not opposed to a long term plan to possibly change C-x, C-c, and
> C-v.

Well, I don't want things like

"In order to move to the other end of the currently active region, press
C-x, and then press C-x within 200ms.  If you are not fast enough, the
region will be erased instead." in the manual for the default behavior.
And yes, I am not making this one up:

cua-prefix-override-inhibit-delay is a variable defined in `cua-base.el'.
Its value is 0.2

Documentation:
If non-nil, time in seconds to delay before overriding prefix key.
If there is additional input within this time, the prefix key is
used as a normal prefix key.  So typing a key sequence quickly will
inhibit overriding the prefix key.
As a special case, if the prefix keys repeated within this time, the
first prefix key is discarded, so typing a prefix key twice in quick
succession will also inhibit overriding the prefix key.
If the value is nil, use a shifted prefix key to inhibit the override.

You can customize this variable.

So before the C-c, C-x, C-v bindings can get their CUA defaults, there
must be some serious key sequence reorganization for Emacs.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Ted Zlatanov <tzz@lifelogs.com>:
> It's always been a nasty hurdle for me, discouraging me from writing new
> stuff. I can never remember the syntax (I deal with Markdown and other
> formats all day, and texinfo gets pushed out).  I also hate having to
> list section names twice and the index and all the other nonsense.
> 
> FWIW, org-mode is all right but Yet Another Format. I think it wouldn't
> be an improvement over texinfo for user adoption. Asciidoc, Docutils, or
> Markdown seem much better if we want to make contributions easy.

Ted is perfectly representative of the younger developers I run into.
When I use terms like "ugly" and "heavyweight", misfeatures like the
duplication of structure in sections and nodes are part of what I have
in mind.

Ted is what's normal out there. It's the handful of people on this list
so used to Texinfo that it has worn grooves in their brains who are
the outliers.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[Alan Mackenzie]

Hello, Eli.

On Mon, Dec 08, 2014 at 06:08:26PM +0200, Eli Zaretskii wrote:
> > From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> > Cc: <esr@thyrsus.com>,  <cwebber@dustycloud.org>,  <ruediger@c-plusplus.de>,  <emacs-devel@gnu.org>
> > Date: Mon, 08 Dec 2014 12:33:38 +0000

> > Eli Zaretskii <address@hidden> writes:

> > >> > But a lot of this is cosmetic.  We could improve Texinfo to look much
> > >> > better probably (and that would positively affect a lot of existing GNU
> > >> > projects).

> > >> But it would still be Texinfo, still be an essentially pointless
> > >> barrier to learning how to contribute.

> > > Nonsense.  What evidence do you have to back that up?

> > I think it is intrinsically hard to get evidence for why people do NOT
> > do something.

> What I had in mind was some evidence, even anecdotal one, that people
> considered contributing a chunk of docs, but decided against that
> because of Texinfo.

I don't recall any difficulty learning Texinfo at all, and I certainly
didn't find it off-putting.  Back in ~2003, I had done some fairly
substantial Elisp coding, and it needed documenting.  Compared with the
effort needed to learn Emacs and Elisp, I found Texinfo fairly trivial.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Ted is what's normal out there. It's the handful of people on this
> list so used to Texinfo that it has worn grooves in their brains who
> are the outliers.

Didn't you want to focus on your Kung Fu examination until you had time
to prepare yourself for contributing more than gratuitous insults to the
discussion?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Mon, 8 Dec 2014 12:14:37 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> 
> Ted is what's normal out there. It's the handful of people on this list
> so used to Texinfo that it has worn grooves in their brains who are
> the outliers.

But they are the ones who do all the work on documentation.

Re: On being web-friendly and why info must die

[Ted Zlatanov]

On Mon, 08 Dec 2014 19:00:52 +0200 Eli Zaretskii <eliz@gnu.org> wrote: 

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Mon, 08 Dec 2014 11:29:37 -0500
>> 
>> On Mon, 08 Dec 2014 18:08:26 +0200 Eli Zaretskii <eliz@gnu.org> wrote: 
>> 
EZ> What I had in mind was some evidence, even anecdotal one, that people
EZ> considered contributing a chunk of docs, but decided against that
EZ> because of Texinfo.
>> 
>> It's always been a nasty hurdle for me, discouraging me from writing new
>> stuff. I can never remember the syntax (I deal with Markdown and other
>> formats all day, and texinfo gets pushed out).

EZ> (Some of) the syntax gets taken care of by the various Texinfo mode
EZ> commands.  We could also add items to the menu, if that's useful.

It's just tedious stuff.  I get back into it after 15-30 minutes but
it's always a context switch.

>> and the index and all the other nonsense.

EZ> Indexing is part of the real effort -- it's a human activity for which
EZ> there's no automated replacement.  Like writing the text itself --
EZ> there's no alternative to doing that yourself, in any documentation
EZ> system.

I tend to prefer freeform tagging, but agree in general.

EZ> But I will offer you a deal: write plain ASCII, and I will add
EZ> markup.  Deal?

I was answering your earlier question about evidence.  Writing ASCII
docs and asking you to merge them is not fair to you.

On Mon, 8 Dec 2014 12:14:37 -0500 "Eric S. Raymond" <esr@thyrsus.com> wrote: 

ESR> When I use terms like "ugly" and "heavyweight", misfeatures like the
ESR> duplication of structure in sections and nodes are part of what I have
ESR> in mind.

They are annoying, but not fundamentally broken.  You need something
like them, as Eli mentioned.

ESR> Ted is what's normal out there. It's the handful of people on this list
ESR> so used to Texinfo that it has worn grooves in their brains who are
ESR> the outliers.

Come on... no need for that.

Ted

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Ted Zlatanov <tzz@lifelogs.com> writes:

> It's just tedious stuff.  I get back into it after 15-30 minutes but
> it's always a context switch.

Me too.  But that's the case with any markup language I've been in touch
with.  I forget what it's supposed to look like after a couple of
months, so I just cargo cult some markup from other sections, and I'm
off.

If I do something bad, like use @xref istead of @pxref, magical elves
suddenly appear and fix it.

Texinfo isn't any worse than other markup languages.  All modern markup
languages have a really pretty way of generating the "Hello world"
document, but once you start in with the indexing and cross referencing
and and, it always turns complicated and ugly.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Lars Magne Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 08 Dec 2014 19:08:39 +0100
> 
> If I do something bad, like use @xref istead of @pxref, magical elves
> suddenly appear and fix it.

An extra-special Emacs feature, no doubt.

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> cua-mode is a clever and reasonably clean hack, but
>> a hack nevertheless.  So enabling it by default is not really an option.
[...]
> Well, I don't want things like
> "In order to move to the other end of the currently active region, press
> C-x, and then press C-x within 200ms.  If you are not fast enough, the
> region will be erased instead." in the manual for the default behavior.
> And yes, I am not making this one up:

So you're just agreeing.  Good.


        Stefan

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/08/2014 08:23 AM, Eli Zaretskii wrote:
> What is it with you young people ...?

And you kids get off my lawn!

(Apologies to Clint Eastwood.)

Re: On being web-friendly and why info must die

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> cua-mode is a clever and reasonably clean hack, but
>>> a hack nevertheless.  So enabling it by default is not really an option.
> [...]
>> Well, I don't want things like
>> "In order to move to the other end of the currently active region, press
>> C-x, and then press C-x within 200ms.  If you are not fast enough, the
>> region will be erased instead." in the manual for the default behavior.
>> And yes, I am not making this one up:
>
> So you're just agreeing.

Violently but yes.

> Good.

Not everybody finds himself elated sharing my opinions.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> If I do something bad, like use @xref istead of @pxref, magical elves
>> suddenly appear and fix it.
> An extra-special Emacs feature, no doubt.

Actually it's been a standard Emacs feature since about 1995, AFAICT.


        Stefan

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Ted Zlatanov <tzz@lifelogs.com>:

> FWIW, org-mode is all right but Yet Another Format. I think it
> wouldn't be an improvement over texinfo for user adoption. Asciidoc,
> Docutils, or Markdown seem much better if we want to make
> contributions easy.

Well, I've seen org-mode attract users to emacs who otherwise wouldn't
have used emacs (the same way auc-tex attracted LaTeX users to emacs
back in the late 80-ies, early 90-ies).

(Personally I don't see the big need for replacing Texinfo, but if there
is, I think that in an emacs setting, org has an advantage over the
other formats mentioned)

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/07/2014 06:30 PM, Stefan Monnier wrote:
> I think I understand why they don't want to fix the processing speed.
> But we should still push them to provide workarounds.  "Separate
> compilation" would solve this problem

It might, yes.  But that sounds like more work than switching input 
formats would be, if some other input format already has good support 
for most of what we want.

> Indeed the slowdown (factor 100 IIRC last time I measured it) is
> a serious problem.

Absolutely.  Texinfo's performance is a real turnoff for me, and it 
can't be encouraging potential contributors.

One possible way to move forward would be to try one or two alternatives 
(Org mode, Asciidoc, whatever) on something relatively small.  It 
wouldn't have to be an Emacs manual.  We could use the proposed new 
technology or technologies on (say) the Grep manual, and see how well it 
works there.  This would mimic how we already did the Gnulib and Git 
conversions: we first converted smaller projects, and eventually got 
around to Emacs.

Re: On being web-friendly and why info must die

[David Engster]

Paul Eggert writes:
> On 12/07/2014 06:30 PM, Stefan Monnier wrote:
>> I think I understand why they don't want to fix the processing speed.
>> But we should still push them to provide workarounds.  "Separate
>> compilation" would solve this problem
>
> It might, yes.  But that sounds like more work than switching input
> formats would be, if some other input format already has good support
> for most of what we want.
>
>> Indeed the slowdown (factor 100 IIRC last time I measured it) is
>> a serious problem.
>
> Absolutely.  Texinfo's performance is a real turnoff for me, and it
> can't be encouraging potential contributors.

 ~/git-2.2.0/Documentation> time asciidoc -b html user-manual.txt
 asciidoc -b html user-manual.txt  7.26s user 0.02s system 90% cpu 8.068 total

That's for 4.5k lines.

 ~/emacs/doc/misc> time makeinfo --html gnus.texi
 makeinfo --html gnus.texi  2.00s user 0.04s system 85% cpu 2.385 total

That's for 30k lines. Yes, that's texinfo4, of course, but I hear it
still compiles.

I doubt we will be happy with anything that's considerably slower than
texinfo4, which means that whatever we might switch to, it better be
written in something that's fast. That already rules out asciidoc and
Org.

-David

Re: On being web-friendly and why info must die

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> I was answering your earlier question about evidence.  Writing ASCII
> docs and asking you [Eli] to merge them is not fair to you.

Shrug.  Making use of voluntary work without contributing back anything
at all is "not fair", and it's what the majority of Emacs users do.
That's more or less a builtin and _wanted_ side effect that the
contributors perfectly well are aware of.

You are not asking to do nothing but merely offering to do the actual
work requiring actual creative thinking.  And Eli has offered to do
finger exercises on it to get the benefits of work you otherwise would
be loathe to do.

I don't see how taking him up on that offer would be unfair to him any
more than free software is anyway.  He gets documentation work done for
lots less of effort than if he had to do it all himself.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

David Engster <deng@randomsample.de> writes:

> Paul Eggert writes:
>> On 12/07/2014 06:30 PM, Stefan Monnier wrote:
>>> I think I understand why they don't want to fix the processing speed.
>>> But we should still push them to provide workarounds.  "Separate
>>> compilation" would solve this problem
>>
>> It might, yes.  But that sounds like more work than switching input
>> formats would be, if some other input format already has good support
>> for most of what we want.
>>
>>> Indeed the slowdown (factor 100 IIRC last time I measured it) is
>>> a serious problem.
>>
>> Absolutely.  Texinfo's performance is a real turnoff for me, and it
>> can't be encouraging potential contributors.
>
>  ~/git-2.2.0/Documentation> time asciidoc -b html user-manual.txt
>  asciidoc -b html user-manual.txt  7.26s user 0.02s system 90% cpu 8.068 total
>
> That's for 4.5k lines.
>
>  ~/emacs/doc/misc> time makeinfo --html gnus.texi
>  makeinfo --html gnus.texi  2.00s user 0.04s system 85% cpu 2.385 total
>
> That's for 30k lines. Yes, that's texinfo4, of course, but I hear it
> still compiles.
>
> I doubt we will be happy with anything that's considerably slower than
> texinfo4, which means that whatever we might switch to, it better be
> written in something that's fast. That already rules out asciidoc and
> Org.

I don't actually see the big deal in compilation times for a full
compilation.  It's not like one does it all the time.  If we are talking
about proofreading, then it might be worth investigating how we can get
partial compilation better to work in Texinfo editing modes.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

David Kastrup <dak@gnu.org> writes:

>> So you're just agreeing.
>
> Violently but yes.

We should introduce a new mailing list style guide: No message in
agreement with anything, even slightly, shall be posted.

And Subject headers should end with a full stop and be less than 27
characters.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> David Kastrup <dak@gnu.org> writes:
>
>>> So you're just agreeing.
>>
>> Violently but yes.
>
> We should introduce a new mailing list style guide: No message in
> agreement with anything, even slightly, shall be posted.

I think that the Emacs developer list is already close enough that such
a style guide would not be worth the trouble.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Lars Magne Ingebrigtsen <larsi@gnus.org>,  emacs-devel@gnu.org
> Date: Mon, 08 Dec 2014 13:57:11 -0500
> 
> >> If I do something bad, like use @xref istead of @pxref, magical elves
> >> suddenly appear and fix it.
> > An extra-special Emacs feature, no doubt.
> 
> Actually it's been a standard Emacs feature since about 1995, AFAICT.

Almost everything that's standard in Emacs is extra-special.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Do you mean, outside of `org-mode' itself? If so, i don't
  > know. Otherwise, yes, many people write academic papers, presentations
  > etc. in Org format, then export to LaTeX; cf.

That's good.  Maybe Org format would be a usable source format if and
when we can make HTML a suitable replacement Info format.  (Or if Org
format can generate Info format -- but that's not as desirable.)

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Alternative input formats

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Fundamentally, I'm still uncertain about the desired goal of replacing
  > Info.

To move to a format that is widely used and widely supported,
and that can handle a broader range of formatting and content.

Even if we have to stick to a subset of HTML
that Emacs can display, it will still support a lot more
than we can now represent in Info.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Alternative input formats

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > How about calling the subset "InfoML, the Info-featured HTML subset"?
  > It would also need to spec a CSS subset, I think (see below).

Seems reasonable.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

> That's good.  Maybe Org format would be a usable source format if and
> when we can make HTML a suitable replacement Info format.  (Or if Org
> format can generate Info format -- but that's not as desirable.)

Emacs org-mode can generate texinfo, which in turn can be processed into
info using the usual toolchain.

(good for writing a GNU manual with org in the current state, but
probably useless for creating a Texinfo replacement...)

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> I think I understand why they don't want to fix the processing speed.
>> But we should still push them to provide workarounds.  "Separate
>> compilation" would solve this problem
> It might, yes.  But that sounds like more work than switching input formats
> would be,

Why?  Are you saying this would require work on our side?  I'd assume
this work would mostly be on the Texinfo-maintainers side.


        Stefan

Re: On being web-friendly and why info must die

[chad]

> On 08 Dec 2014, at 13:41, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>> I think I understand why they don't want to fix the processing speed.
>>> But we should still push them to provide workarounds.  "Separate
>>> compilation" would solve this problem
>> It might, yes.  But that sounds like more work than switching input formats
>> would be,
> 
> Why?  Are you saying this would require work on our side?  I'd assume
> this work would mostly be on the Texinfo-maintainers side.

Haven't the Texinfo maintainers already repeatedly said "yes, we
know the new version is very slow. We can't find anyone to do the
necessary work otherwise.", thus forcing the choice between speed
and unicode support?

~Chad

Re: On being web-friendly and why info must die

[Ted Zlatanov]

On Mon, 08 Dec 2014 21:27:59 +0100 David Kastrup <dak@gnu.org> wrote: 

DK> Ted Zlatanov <tzz@lifelogs.com> writes:
>> I was answering your earlier question about evidence.  Writing ASCII
>> docs and asking you [Eli] to merge them is not fair to you.

DK> Shrug.  Making use of voluntary work without contributing back anything
DK> at all is "not fair", and it's what the majority of Emacs users do.
DK> That's more or less a builtin and _wanted_ side effect that the
DK> contributors perfectly well are aware of.

I mean, I could spend 15-30 minutes and get back to speed. Dumping work
on Eli doesn't scale, regardless of how willing he is to take it.

But more to the point of this thread, I actually *fear* those 15-30
minutes because it's mostly hunting for "how the hell do you highlight"
and "how do you update the index" and "will this break the docs and
annoy people" in my long-term memory. It's annoying. By contrast, I can
start typing Markdown very quickly because I already use it all the
time. This happens for me with any context switch, so I generally tend
to work in large blocks instead of switching tasks quickly.

As for Asciidoc, I looked into it. It's fairly compatible with Markdown
except it has tables and other things codified better, and its own
markup, and some of it looks like old-school manpages. I could live with
it, if Markdown was not an option (so it would be my second choice). Org
markup would still be last on my list because it's indisputably exotic,
as much as I like it. So my list of documentation format preferences
would be Markdown, then Asciidoc, then texinfo, and last Org. But that
doesn't mean I advocate switching, if anyone cares :)

Ted

Re: On being web-friendly and why info must die

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Mon, 08 Dec 2014 21:27:59 +0100 David Kastrup <dak@gnu.org> wrote: 
>
> DK> Ted Zlatanov <tzz@lifelogs.com> writes:
>>> I was answering your earlier question about evidence.  Writing ASCII
>>> docs and asking you [Eli] to merge them is not fair to you.
>
> DK> Shrug.  Making use of voluntary work without contributing back anything
> DK> at all is "not fair", and it's what the majority of Emacs users do.
> DK> That's more or less a builtin and _wanted_ side effect that the
> DK> contributors perfectly well are aware of.
>
> I mean, I could spend 15-30 minutes and get back to speed. Dumping work
> on Eli doesn't scale, regardless of how willing he is to take it.

How does it not scale?  Do you think Eli will spend more time and effort
on your manual entries than you, and when you write twice the amount,
he'll have to invest more than twice the work?

What does "doesn't scale" mean in this context?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

David Kastrup <dak@gnu.org> writes:

> How does it not scale?  Do you think Eli will spend more time and effort
> on your manual entries than you, and when you write twice the amount,
> he'll have to invest more than twice the work?
>
> What does "doesn't scale" mean in this context?

Well, as incredibly as it sounds, Eli is (presumably) just one person,
while the number of people who are not Eli is a whole lot bigger than
1.

So having Eli do all the markup for everybody who is not Eli doesn't
really scale well.  It would be better if everybody could do the markup
themselves.

(This is not a vote for changing from Texinfo, either, if anybody is
counting.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> How does it not scale?  Do you think Eli will spend more time and effort
>> on your manual entries than you, and when you write twice the amount,
>> he'll have to invest more than twice the work?
>>
>> What does "doesn't scale" mean in this context?
>
> Well, as incredibly as it sounds, Eli is (presumably) just one person,
> while the number of people who are not Eli is a whole lot bigger than
> 1.
>
> So having Eli do all the markup for everybody who is not Eli doesn't
> really scale well.

So far, it scales perfectly well.  Because all of those people for whom
Texinfo is the hurdle keeping them from writing documentation find
themselves a different reason.  Not wanting to overwork Eli is one of
the more ridiculous ones since it does not appear that he actually had
to spend more than an hour of his life so far putting Texinfo markup
into batches of new documentation.

> It would be better if everybody could do the markup themselves.

Yeah, it's too sad, all of those pages of finished documentation people
have lying around that are just missing the Texinfo markup because
nobody would want to overwork Eli or anybody else on the list.

Get real.  Texinfo is not the excuse for not finishing documentation
work, it is the excuse for not even starting it.  Get rid of Texinfo,
and people will find another excuse.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stefan Monnier]

>>>> I think I understand why they don't want to fix the processing speed.
>>>> But we should still push them to provide workarounds.  "Separate
>>>> compilation" would solve this problem
>>> It might, yes.  But that sounds like more work than switching input formats
>>> would be,
>> Why?  Are you saying this would require work on our side?  I'd assume
>> this work would mostly be on the Texinfo-maintainers side.
> Haven't the Texinfo maintainers already repeatedly said "yes, we
> know the new version is very slow. We can't find anyone to do the
> necessary work otherwise.", thus forcing the choice between speed
> and unicode support?

That's not what I'm talking about.  I know that the MB/s processed by
Texinfo-5 is much slower than Texinfo-4 and is unlikely to improve
noticeably in the foreseeable future.  What I'm asking is whether
Texinfo-5 could be improved so that it can do the work by processing
fewer megabytes, because it would only process the modified files: the
Elisp manual is about 3MB of Texinfo code, but usually you only work on
a single one of those files, which is at most 300kB, so doing
separate-compilation would give you a speed up of at least 10, making
the result a lot more tolerable (and on which we can have control, so if
it's still not fast enough we can split the manual into smaller files).


        Stefan

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: chad <yandros@gmail.com>
> Date: Mon, 8 Dec 2014 15:39:21 -0800
> 
> Haven't the Texinfo maintainers already repeatedly said "yes, we
> know the new version is very slow. We can't find anyone to do the
> necessary work otherwise.", thus forcing the choice between speed
> and unicode support?

It wasn't about Unicode support (Texinfo 4.x did it almost as well,
the difference being in the language, not in the translator).  The
issue at hand was the continued development of makeinfo per se.

Meanwhile, isn't there a way to compile Perl programs into C?  Maybe
this will make the result acceptable.

Re: Alternative input formats

[Mike Gerwitz]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Mon, Dec 08, 2014 at 12:42:30 +0900, Stephen J. Turnbull wrote:
> How about calling the subset "InfoML, the Info-featured HTML subset"?
> It would also need to spec a CSS subset, I think (see below).

HTML is intended to be the document format, and is intended to be
semantic.[2] CSS is display-only.  Therefore, it makes sense that Emacs
would define its own (user-configurable) stylesheet, or generate one
- From faces, but HTML documents should always be able to stand on their
own.

> Other than that we need faces, and I would suggest prohibiting EM (and
> I!) and STRONG (ditto B!) elements in favor of semantic markup on DIV
> and SPAN elements ('class="nextNode"' and the like).

As was mentioned already, the whole purpose of these elements is to
provide semantics to a document; classes exist purely for styling (and
many JavaScript programs use them as metadata, though that practice is
being largely deprecated by HTML5 data attributes).

The problem with documents on the web today is that they are a mess of
output from various systems with no regard to proper structure, treating
the browser's rendering as if it were semantic.  This is wrong.

HTML5 defines a whole new set of semantic elements (that will simply not
render in older browsers, so no harm done in most cases) to address the
issue.[0]  For example, using

  <div class="article">

is useless, since `div' is ambiguous---it is used for everything!  When
a program parses the web page, what should it do?  Attempt to guess,
based on the class name(s), what data are represented by the node?

Instead, the `article' tag was introduced, along with many others, to
provide a standard document structure.[1]

  <article>
    <section>
      <h1>My Definitions</h1>
      <p>Below is a list of my definitions.</p>
      <dl>
        <dt>Some Term</dt>
        <dd>Some definition that uses <em>semantic</em> markup.</dd>
      </dl>
    </section>

    <section>
      <h1>Another Section</h1>
      <!-- ... -->
    </section>
  </article>

> And links, but Emacs already knows how to do that.

Links generally need more love; the @rel attribute aims to solve that.

[0]: https://developer.mozilla.org/en/docs/Web/Guide/HTML/HTML5/HTML5_element_list
[1]: https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Sections_and_Outlines_of_an_HTML5_document
[2]: http://en.wikipedia.org/wiki/Semantic_HTML


- -- 
Mike Gerwitz
Free Software Hacker | GNU Maintainer
http://mikegerwitz.com
FSF Member #5804 | GPG Key ID: 0x8EE30EAB
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iQIcBAEBAgAGBQJUhnliAAoJEPIruBWO4w6rapcP/37r6LOpQF1jw0E0b8Ou7RW9
HDjIxW6zH0NiefboQHw00bGFreZz1R4hrhYLSKws2c7nozQH8TAT/ds3eFqGzOS3
raya2T2+BYL0eDXVdhtY4c7FWIPo1kxr5th5sXANLtcVjMsqUPoJY5MJ5Tr/2eup
sopzGyrlon5B5cMWkcGW7OR4g73o/s0WOB9UM5M5J1ato7xCiH7j7NZ3vheEEqFZ
1zBW211tksgL38iw+Wz46Sgy7VUky0277mdCYdDMhLt9suInz81BgLfETWLbeu1t
Umf0xvABCWoM6DXw5Vxh5sKcuWEva9th9YxDoYDBzgpqYs1amq3m6RcyW2AYjg1f
lrX9IVOu0hPOapg24u2ZcjkajaqVyBoHQklpv0CjsmXTiwKZRc5GRYrANA9/C7wk
sV/efuJwOd8NT1FLHOD3rBTeF56kEICHFvSCuB/791RF3QfV1tF12Gik/pi4vJ+n
CUKg1hMJgyr4f4dD26Ar2QHMp0UDG3wJfyn2nW93JsaMOmbaeVBvSiRzb/dXz7Gu
LA5zVmcN4g+ZuhnVciLA0Y17+y2ji37T6uJy9HQT4DOdDe6BaDLmNJ/v6LMfGnx9
SS/AWxPHtGZHaGyW4+KHLMP6mQw7paTV6jnUi4vSf6VtGhlCKrHdDmx8ryyNxLYM
0ysiN8haXEICvMvArcaw
=Oask
-----END PGP SIGNATURE-----

Re: On being web-friendly and why info must die

[Paul Eggert]

David Engster wrote:
>   ~/git-2.2.0/Documentation> time asciidoc -b html user-manual.txt
>   asciidoc -b html user-manual.txt  7.26s user 0.02s system 90% cpu 8.068 total
>
> That's for 4.5k lines.
>
>   ~/emacs/doc/misc> time makeinfo --html gnus.texi
>   makeinfo --html gnus.texi  2.00s user 0.04s system 85% cpu 2.385 total
>
> That's for 30k lines. Yes, that's texinfo4, of course

That's a bit unfair to Texinfo, since gnus.texi @includes other files, and one 
should count all its input lines.  Conversely, Texinfo 4 is no longer maintained 
and misses some useful new features, so one should measure Texinfo 5, which is 
waaayyy slooower.  Furthermore, the (newer) asciidoctor is an order of magnitude 
faster than the (older) asciidoc, and it's not entirely fair to be using the 
way-slower variant in a benchmark.

So overall I'm afraid the above numbers don't mean all that much.

Re: On being web-friendly and why info must die

[Paul Eggert]

Stefan Monnier wrote:
>>> I think I understand why they don't want to fix the processing speed.
>>> But we should still push them to provide workarounds.  "Separate
>>> compilation" would solve this problem
>> It might, yes.  But that sounds like more work than switching input formats
>> would be,
>
> Why?  Are you saying this would require work on our side?

Yes, partly.  Separate compilation usually requires some extra work on the 
source code side.

> I'd assume
> this work would mostly be on the Texinfo-maintainers side.

Yes, that sounds plausible.  But I doubt whether the work will happen, as 
separate compilation for Texinfo doesn't sound that easy, and the Texinfo 
developers don't seem to have a lot of cycles to spare.

Re: On being web-friendly and why info must die

[Paul Eggert]

David Kastrup wrote:
> I don't actually see the big deal in compilation times for a full
> compilation.  It's not like one does it all the time.

I do it all the time when I'm editing manuals, because I want to check the 
output.  Or at least, I *used* to do it back when Texinfo was reasonably fast.

Also, if I check out another branch and do a "make", the other branch may have 
different manuals and so this may force "make" to rebuild them, and "make" may 
take a long time, even when using "make -j" -- the manuals are now *so* slow to 
process that they are often on the critical path for "make -j".

I did find a simple way to avoid the performance problem: don't edit the 
documentation and don't switch branches.  But these restrictions are really 
off-putting.  We need to do better.

Re: Alternative input formats

[Stephen J. Turnbull]

Mike Gerwitz writes:
 > Stephen Turnbull wrote:

 > > Other than that we need faces, and I would suggest prohibiting EM (and
 > > I!) and STRONG (ditto B!) elements in favor of semantic markup on DIV
 > > and SPAN elements ('class="nextNode"' and the like).
 > 
 > As was mentioned already, the whole purpose of these elements is to
 > provide semantics to a document; classes exist purely for styling
 > (and many JavaScript programs use them as metadata, though that
 > practice is being largely deprecated by HTML5 data attributes).
 > Instead, the `article' tag was introduced, along with many others,
 > to provide a standard document structure.[1]

Sure.  I think that's great for blogs and possibly for Wikipedia.

However, as a non-expert in HTML5, what I worry is that the advantages
of the *semantic* markup in Texinfo which is *tuned* to multi-targeted
(media-wise) software manuals will be obscured by the standardization
process of translating to HTML5.  To recover them, you will have to
use some extension technique, such as "class" attributes or "data
attributes" (whatever they are).  If the standard semantics are quite
accurate for the elements used in Emacs manuals, fine, use the
standard elements.  But if they don't correspond quite accurately, I
personally prefer a language that says what it means even if it's
somewhat clumsy to read (remember, HTML is a *target* language for our
documents, not a source language).

Speaking of Texinfo markup semantics, that's one reason I'm not a big
fan of plain text markup for this purpose.  Sure, you can do it, but
it requires additional annoying syntax in languages like Markdown and
ReStructuredText.  It's hardly prettier and *much* less convenient
(for AUCTeX users) than Texinfo.

Re: On being web-friendly and why info must die

[Thierry Volpiatto]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> It would be better if everybody could do the markup themselves.

Just a note:

I don't know how to write info with texinfo but I remember I wrote manuals in this
format using muse.
Muse is able to convert a file in diverse formats including latex,
texinfo, (x)html and maybe others (Don't remember, long time I didn't
use this).
So writing all documentation in such format would make everybody happy,
allowing to convert the document in various formats.

-- 
Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Re: On being web-friendly and why info must die

[David Kastrup]

Paul Eggert <eggert@cs.ucla.edu> writes:

> David Kastrup wrote:
>> I don't actually see the big deal in compilation times for a full
>> compilation.  It's not like one does it all the time.
>
> I do it all the time when I'm editing manuals, because I want to check
> the output.

But that's one manual then, not all the manuals.

> Or at least, I *used* to do it back when Texinfo was reasonably fast.

Make doc for LilyPond takes over an hour.  The time spent in Texinfo is
few minutes of that even in Texinfo 5.

Gcc was also really much slower than Turbo C in the days and I got over
it.

> Also, if I check out another branch and do a "make", the other branch
> may have different manuals and so this may force "make" to rebuild
> them, and "make" may take a long time, even when using "make -j" --
> the manuals are now *so* slow to process that they are often on the
> critical path for "make -j".

When compiling Emacs, I tend to see pretty much all of the time after
touching a large file set spent in the C compiler and
byte-compiling/autoload generating.

> I did find a simple way to avoid the performance problem: don't edit
> the documentation and don't switch branches.  But these restrictions
> are really off-putting.  We need to do better.

Well, Texinfo is a small project.  If one is serious about wanting to
invest time ("we need to do better" suggests so), it is likely spent
quite effectively there.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Thierry Volpiatto <thierry.volpiatto@gmail.com> writes:

> Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
>
>> It would be better if everybody could do the markup themselves.
>
> Just a note:
>
> I don't know how to write info with texinfo but I remember I wrote manuals in this
> format using muse.
> Muse is able to convert a file in diverse formats including latex,
> texinfo, (x)html and maybe others (Don't remember, long time I didn't
> use this).
> So writing all documentation in such format would make everybody happy,
> allowing to convert the document in various formats.

I am flabbergasted at the number of people not understanding the
difference between source and target formats.  Conversions are only an
option for editing source files when they are round-trip safe including
all source formatting and comments.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Even for emacs docs. Google does word stemming
  > and alternatives, so if you search for something related "modification"
  > then google also finds matches with "changing", "altering", etc.

We could implement search like that in Emacs, too.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Emacs org-mode can generate texinfo, which in turn can be processed into
  > info using the usual toolchain.

If Org format can be converted into Texinfo _and can generate
everything you need in the Texinfo file to make a good looking manual_
then it is an acceptable source format for GNU manuals under our
current standards.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Ted Zlatanov]

On Tue, 09 Dec 2014 03:18:54 +0100 David Kastrup <dak@gnu.org> wrote: 

DK> Yeah, it's too sad, all of those pages of finished documentation people
DK> have lying around that are just missing the Texinfo markup because
DK> nobody would want to overwork Eli or anybody else on the list.

DK> Get real.  Texinfo is not the excuse for not finishing documentation
DK> work, it is the excuse for not even starting it.  Get rid of Texinfo,
DK> and people will find another excuse.

I appreciate the sarcasm, but stand by my original statement that
there's a texinfo 15-30 minute ramp-up time that's annoying and puts
*me* off. You can call it an excuse if you wish.

Ted

Re: On being web-friendly and why info must die

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Tue, 09 Dec 2014 03:18:54 +0100 David Kastrup <dak@gnu.org> wrote: 
>
> DK> Yeah, it's too sad, all of those pages of finished documentation people
> DK> have lying around that are just missing the Texinfo markup because
> DK> nobody would want to overwork Eli or anybody else on the list.
>
> DK> Get real.  Texinfo is not the excuse for not finishing documentation
> DK> work, it is the excuse for not even starting it.  Get rid of Texinfo,
> DK> and people will find another excuse.
>
> I appreciate the sarcasm, but stand by my original statement that
> there's a texinfo 15-30 minute ramp-up time that's annoying and puts
> *me* off. You can call it an excuse if you wish.

You have the offer to just write the text and leave the "rampup time" to
someone else.  If you don't want to call it an excuse, call it an
imaginary hurdle.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Jay Belanger]

> but stand by my original statement that there's a texinfo 15-30 minute
> ramp-up time that's annoying and puts *me* off. You can call it an
> excuse if you wish.

It's a legitimate issue, but not specific to TeXinfo; the same issue
arises no matter what we use for documentation.  There will be
a ramp-up time for anyone who doesn't use the system regularly.

Instead of making writers look into the doc sources for examples of what
they want to do, it might be useful to have a page or two of examples of
using TeXinfo (or whatever).

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Lars Magne Ingebrigtsen <larsi@gnus.org>
> Date: Tue, 09 Dec 2014 02:31:06 +0100
> Cc: emacs-devel@gnu.org
> 
> So having Eli do all the markup for everybody who is not Eli doesn't
> really scale well.

I wouldn't worry about that bridge until we actually get there.

> It would be better if everybody could do the markup themselves.

Yes, of course.  But having more people write docs sans the markup is
still better than leaving everything documentation-wise to 2.5 people.

Re: On being web-friendly and why info must die

[Stefan Monnier]

> Yes, that sounds plausible.  But I doubt whether the work will happen, as
> separate compilation for Texinfo doesn't sound that easy, and the Texinfo
> developers don't seem to have a lot of cycles to spare.

We should at least ask for it.  Myself, I'd be happy with a "low
quality" support for separate compilation where some aspects of the
result are not necessarily quite identical to what the "whole text
compilation" would give.


        Stefan

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 08 Dec 2014 21:19:34 -0500
> Cc: emacs <emacs-devel@gnu.org>
> 
> That's not what I'm talking about.  I know that the MB/s processed by
> Texinfo-5 is much slower than Texinfo-4 and is unlikely to improve
> noticeably in the foreseeable future.  What I'm asking is whether
> Texinfo-5 could be improved so that it can do the work by processing
> fewer megabytes, because it would only process the modified files: the
> Elisp manual is about 3MB of Texinfo code, but usually you only work on
> a single one of those files, which is at most 300kB, so doing
> separate-compilation would give you a speed up of at least 10, making
> the result a lot more tolerable (and on which we can have control, so if
> it's still not fast enough we can split the manual into smaller files).

Makeinfo validates pointers and cross-references that could lead into
many other parts.  Separate compilation would need to leave some info
about those other parts in a form that is much more easily readable.

And then there's the --split-size option, the Index nodes (which are
computed from the entire document, and index entries from a single
file are non-contiguous), and other complications.  HTML output has
more of them, btw.

Sounds like a nice project.  How about bringing it up on the Texinfo
list?  Who knows, we might get lucky.

Re: On being web-friendly and why info must die

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Mon, 08 Dec 2014 21:19:34 -0500
>> Cc: emacs <emacs-devel@gnu.org>
>> 
>> That's not what I'm talking about.  I know that the MB/s processed by
>> Texinfo-5 is much slower than Texinfo-4 and is unlikely to improve
>> noticeably in the foreseeable future.  What I'm asking is whether
>> Texinfo-5 could be improved so that it can do the work by processing
>> fewer megabytes, because it would only process the modified files: the
>> Elisp manual is about 3MB of Texinfo code, but usually you only work on
>> a single one of those files, which is at most 300kB, so doing
>> separate-compilation would give you a speed up of at least 10, making
>> the result a lot more tolerable (and on which we can have control, so if
>> it's still not fast enough we can split the manual into smaller files).
>
> Makeinfo validates pointers and cross-references that could lead into
> many other parts.  Separate compilation would need to leave some info
> about those other parts in a form that is much more easily readable.

Much more easily readable than Texinfo source?  Texinfo source does not
seem hard to parse to me.  What am I overlooking?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Tue, 09 Dec 2014 18:28:43 +0100
> 
> > Makeinfo validates pointers and cross-references that could lead into
> > many other parts.  Separate compilation would need to leave some info
> > about those other parts in a form that is much more easily readable.
> 
> Much more easily readable than Texinfo source?  Texinfo source does not
> seem hard to parse to me.  What am I overlooking?

Not sure.  But then why is the Perl implementation so slow?  I thought
one reason was that it was built around a parser, something the
original C version didn't even try to do.

Re: On being web-friendly and why info must die

[Ivan Shmakov]

>>>>> David Kastrup <dak@gnu.org> writes:
>>>>> Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

[…]

 >> It would be better if everybody could do the markup themselves.

 > Yeah, it's too sad, all of those pages of finished documentation
 > people have lying around that are just missing the Texinfo markup
 > because nobody would want to overwork Eli or anybody else on the
 > list.

	… And just in case that is indeed a concern – or becomes one in
	the foreseeable future – may I request for a tag to be added to
	Debbugs for the contributions lacking proper Texinfo markup?

	I sure can promise to visit the bugs so tagged from time to
	time.  (I’m not familiar with Texinfo per se, but I used to be
	quite knowledgeable about LaTeX, and given that one incarnation
	of Texinfo is nothing else than texinfo.tex, I guess it counts.)

[…]

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[andres.ramirez]

At Tue, 09 Dec 2014 19:39:06 +0200,
Eli Zaretskii wrote:
> 
> > From: David Kastrup <dak@gnu.org>
> > Date: Tue, 09 Dec 2014 18:28:43 +0100
> > 
> > > Makeinfo validates pointers and cross-references that could lead into
> > > many other parts.  Separate compilation would need to leave some info
> > > about those other parts in a form that is much more easily readable.
> > 
> > Much more easily readable than Texinfo source?  Texinfo source does not
> > seem hard to parse to me.  What am I overlooking?
> 
> Not sure.  But then why is the Perl implementation so slow?  I thought
> one reason was that it was built around a parser, something the
> original C version didn't even try to do.
> 
> 
Mmmm. It should be another reasons, a parser can be done on C too(Flex/Bison). But
the Texinfo guys had chosen perl in place o C. In my humble opinion,
the best option would have been make everything on C. I think the main
users of Texinfo is the emacs community (Everyone compiling
the trunk)

Am I Right in my last statement?.

Best Regards

Re: On being web-friendly and why info must die

[Karl Fogel]

Richard Stallman <rms@gnu.org> writes:
>Is there software to generate TeX input from Org format?

There is a general solution to this problem -- Pandoc, the "universal document converter".  http://johnmacfarlane.net/pandoc/

Pandoc supports Org as an input format (and output too, though we don't need that here).  Pandoc is free software (GPL v2 or later).

  $ pandoc --help
  
  pandoc [OPTIONS] [FILES]
  Input formats:  docbook, haddock, html, json, latex, markdown, markdown_github,
                  markdown_mmd, markdown_phpextra, markdown_strict, mediawiki,
                  native, opml, org, rst, textile
  Output formats: asciidoc, beamer, context, docbook, docx, dzslides, epub, epub3,
                  fb2, html, html5, icml, json, latex, man, markdown,
                  markdown_github, markdown_mmd, markdown_phpextra,
                  markdown_strict, mediawiki, native, odt, opendocument, opml,
                  org, pdf*, plain, revealjs, rst, rtf, s5, slideous, slidy,
                  texinfo, textile
                  [*for pdf output, use latex or beamer and -o FILENAME.pdf]
  [...]

Best,
-Karl

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Tue, 09 Dec 2014 14:50:19 -0500
> From: andres.ramirez <andres.ramirez@kipuamutay.com>
> Cc: David Kastrup <dak@gnu.org>,
> 	emacs-devel@gnu.org
> 
> Mmmm. It should be another reasons, a parser can be done on C
> too(Flex/Bison).

The Perl version already existed, at least most of it.  And there was
a programmer willing to develop it.

> I think the main users of Texinfo is the emacs community (Everyone
> compiling the trunk)
> 
> Am I Right in my last statement?.

No.  Texinfo is used by all GNU projects alike.

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/09/2014 12:57 AM, David Kastrup wrote:
>
>> I do it all the time when I'm editing manuals, because I want to check
>> the output.
> But that's one manual then, not all the manuals.

Sometimes it's just one Emacs manual, but often enough I'm editing 
multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is 
still waayyy toooo sloooowww.

> Make doc for LilyPond takes over an hour.

That's too bad.  It shouldn't take an hour to check out one's changes to 
the documentation.  That's a sure way to discourage contributions to the 
documentation.

> Texinfo is a small project. If one is serious about wanting to invest 
> time ("we need to do better" suggests so), it is likely spent quite 
> effectively there. 

Only if we assume that Texinfo is the way to go for the future.  If not, 
our time is spent more effectively elsewhere.

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Sometimes it's just one Emacs manual, but often enough I'm editing
> multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is
> still waayyy toooo sloooowww.

Texinfo 4 is still available, isn't it?  I can't recall whether I
installed it myself or it was just there, but I found Texinfo 5
unbearable and switched.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/09/2014 02:00 PM, Lars Magne Ingebrigtsen wrote:
> Texinfo 4 is still available, isn't it?  I can't recall whether I
> installed it myself or it was just there, but I found Texinfo 5
> unbearable and switched.

And that's a problem.  The fact that so many core Emacs contributors 
stick with Texinfo 4 is not only a technical problem (Texinfo 4 doesn't 
check syntax typos as well, it is still quoting 1970s-style, etc.), it's 
a marketing problem as we're giving potential contributors the 
impression that our development process has ossified.

Re: On being web-friendly and why info must die

[Ulrich Mueller]

>>>>> On Tue, 09 Dec 2014, Karl Fogel wrote:

> There is a general solution to this problem -- Pandoc, the
> "universal document converter". http://johnmacfarlane.net/pandoc/

> Pandoc supports Org as an input format (and output too, though we
> don't need that here). Pandoc is free software (GPL v2 or later).

In my experience Pandoc has its limitations. In the cases where I have
used it to convert from LaTeX to other formats like HTML or Mediawiki,
many things broke and the output required massive manual reworking.
My conclusion was that I could use it as a starting point for a
one-shot conversion, but that it would be unsuitable for regular
automatic conversions.

Ulrich

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Here is an example-based walkthrough of a subset of the format:
  >  http://steinar.bang.priv.no/2012/05/02/using-org-mode/

This expains how to use Org mode to edit outlines, track times, and
other things that are not particularly useful for me.

It does not explain how to use Org format to format a manual.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 12/09/2014 02:00 PM, Lars Magne Ingebrigtsen wrote:
>> Texinfo 4 is still available, isn't it?  I can't recall whether I
>> installed it myself or it was just there, but I found Texinfo 5
>> unbearable and switched.
>
> And that's a problem.  The fact that so many core Emacs contributors
> stick with Texinfo 4 is not only a technical problem (Texinfo 4
> doesn't check syntax typos as well, it is still quoting 1970s-style,
> etc.), it's a marketing problem as we're giving potential contributors
> the impression that our development process has ossified.

Yes.  The way the Texinfo maintainers dropped the ball here is perhaps
the best argument (so far) for why Emacs should switch to a different
input format.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Eric S. Raymond]

Ulrich Mueller <ulm@gentoo.org>:
> >>>>> On Tue, 09 Dec 2014, Karl Fogel wrote:
> 
> > There is a general solution to this problem -- Pandoc, the
> > "universal document converter". http://johnmacfarlane.net/pandoc/
> 
> > Pandoc supports Org as an input format (and output too, though we
> > don't need that here). Pandoc is free software (GPL v2 or later).
> 
> In my experience Pandoc has its limitations. In the cases where I have
> used it to convert from LaTeX to other formats like HTML or Mediawiki,
> many things broke and the output required massive manual reworking.
> My conclusion was that I could use it as a starting point for a
> one-shot conversion, but that it would be unsuitable for regular
> automatic conversions.
> 
> Ulrich

I agree.  These problems are real, and relate not only to quality of
implementation but to weaknesses in Markdown.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 12/09/2014 12:57 AM, David Kastrup wrote:
>>
>>> I do it all the time when I'm editing manuals, because I want to check
>>> the output.
>> But that's one manual then, not all the manuals.
>
> Sometimes it's just one Emacs manual, but often enough I'm editing
> multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is
> still waayyy toooo sloooowww.
>
>> Make doc for LilyPond takes over an hour.
>
> That's too bad.  It shouldn't take an hour to check out one's changes
> to the documentation.  That's a sure way to discourage contributions
> to the documentation.

Not really.  For one thing, the normal "make" creates the Info
documentation (and no HTML docs at all) without images.  That catches at
least syntax errors in the text parts, and it's probably half a minute
of the overall compile time.  It's not much of a help for the
translators though since we provide Info only for English.

For another, if you create a documentation patch and submit it to our
tracker, it is picked up by the compile farms and tested for building
properly (including full documentation).

And third, the dependencies are done pretty well.  If you change one
source file, only the corresponding Info/HTML/PDF document gets
regenerated, and only changed images (which take the bulk of the time)
are recompiled: a system of hashing makes sure that any changes in the
image source result in a new file name for the file extracted from the
embedded source.

Of course, if you change the LilyPond executable and expect changes in
the docs because of the changes in the executable responsible for
generating the images, you need to run "make doc-clean": an explicit
dependency of everything on the executable would be too painful.

>> Texinfo is a small project. If one is serious about wanting to
>> invest time ("we need to do better" suggests so), it is likely spent
>> quite effectively there. 
>
> Only if we assume that Texinfo is the way to go for the future.  If
> not, our time is spent more effectively elsewhere.

It's under control of the GNU project and it does the job.  We are free
to spend time in it.  For projects external to GNU, we may or may not
even have the possibility to spend time/effort for making them better
suited for GNU.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Ivan Shmakov <ivan@siamics.net> writes:

> 	… And just in case that is indeed a concern – or becomes one in
> 	the foreseeable future – may I request for a tag to be added to
> 	Debbugs for the contributions lacking proper Texinfo markup?
>
> 	I sure can promise to visit the bugs so tagged from time to
> 	time.  (I’m not familiar with Texinfo per se, but I used to be
> 	quite knowledgeable about LaTeX, and given that one incarnation
> 	of Texinfo is nothing else than texinfo.tex, I guess it counts.)

It doesn't count apart from the AUCTeX keybindings for a number of
Texinfo commands being the same as for the corresponding LaTeX commands.

But Texinfo is really quite different from LaTeX or plain TeX or even
Context, and texinfo.tex is used only for generating the hardcopy
manuals anyway.  If you want to mess with the internals of hardcopy
generation, TeX knowledge will be useful.  Or for debugging crashes.
But not for writing Texinfo documents as such.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> On 12/09/2014 02:00 PM, Lars Magne Ingebrigtsen wrote:
>>> Texinfo 4 is still available, isn't it?  I can't recall whether I
>>> installed it myself or it was just there, but I found Texinfo 5
>>> unbearable and switched.
>>
>> And that's a problem.  The fact that so many core Emacs contributors
>> stick with Texinfo 4 is not only a technical problem (Texinfo 4
>> doesn't check syntax typos as well, it is still quoting 1970s-style,
>> etc.), it's a marketing problem as we're giving potential contributors
>> the impression that our development process has ossified.
>
> Yes.  The way the Texinfo maintainers dropped the ball here is perhaps
> the best argument (so far) for why Emacs should switch to a different
> input format.

The idea of teamplay when one sees a team member drop the ball is not
fingerpointing and defecting in my opinion.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stephen Leake]

Paul Eggert <eggert@cs.ucla.edu> writes:

> I did find a simple way to avoid the performance problem: don't edit
> the documentation and don't switch branches.  But these restrictions
> are really off-putting.  We need to do better.

One workaround while waiting for a faster makeinfo; keep branches in
separate workspaces. That way switching branches doesn't mean
recompiling everything.

We need a good set of git recipes for this approach; I'm working on
writing them up.

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Stephen Leake]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> Sometimes it's just one Emacs manual, but often enough I'm editing
>> multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is
>> still waayyy toooo sloooowww.
>
> Texinfo 4 is still available, isn't it?  

Not in Cygwin, which is where I get texinfo for Windows.

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Rasmus]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Here is an example-based walkthrough of a subset of the format:
>   >  http://steinar.bang.priv.no/2012/05/02/using-org-mode/
>
> This expains how to use Org mode to edit outlines, track times, and
> other things that are not particularly useful for me.

If you explain exactly what are the features you need to write a manual it
will be easier to provide good documentation.

> It does not explain how to use Org format to format a manual.

As noted earlier, also check out Ch. 11 and Ch. 12 of the quick guide
   http://orgmode.org/guide/Markup.html#Markup
   http://orgmode.org/guide/Exporting.html#Exporting

Maybe parts of of Ch. 2:
   http://orgmode.org/guide/Document-Structure.html#Document-Structure

For Texinfo export/indexing:
    (info "(org) Texinfo export")
For an example of a Texinfo manual:
    (info "(org) An example")

All of these are a couple of pages.

—Rasmus

-- 
El Rey ha muerto. ¡Larga vida al Rey!

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

>> Here is an example-based walkthrough of a subset of the format:
>>  http://steinar.bang.priv.no/2012/05/02/using-org-mode/

> This expains how to use Org mode to edit outlines, track times, and
> other things that are not particularly useful for me.

> It does not explain how to use Org format to format a manual.

There is an example in that Org document for a memo which shows basic
document structure, and some formatting (a C code example).  That's what
I intended you to see.

That "memo" subtree of the outline can be exported as, LaTeX, Texinfo,
Libreoffice, plain text, asciidoc, etc.

What that "memo" example is (currently) missing is basic formatting
(*bold*, _underline_ and /italics/ (this is how bold, underline and
italics are done in org)), cross-referencing, and weblinks (which are
important for a manual).

I'll put all of the above into that example, if I find the time.

(But even with the extras added, the org example document will be in the
"hello world" document class, and as Lars said in a different place in
this thread: "hello world" documents for all markup languages look clear
and understandable)

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Steinar Bang <sb@dod.no> writes:

> (But even with the extras added, the org example document will be in the
> "hello world" document class, and as Lars said in a different place in
> this thread: "hello world" documents for all markup languages look clear
> and understandable)

If we're looking for new formats, perhaps the proponents could point us
to example documents in each format used to format a manual?

I've yet to see a real-world "easy formatting" language used in the wild
that didn't make me throw up, just a bit, in my mouth.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> I've yet to see a real-world "easy formatting" language used in the wild
> that didn't make me throw up, just a bit, in my mouth.

But I haven't seen them all!  There may be several!

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: On being web-friendly and why info must die

[Stefan Monnier]

> What that "memo" example is (currently) missing is basic formatting
> (*bold*, _underline_ and /italics/ (this is how bold, underline and

But that's not semantic markup.


        Stefan

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Lars Magne Ingebrigtsen <larsi@gnus.org>:

> If we're looking for new formats, perhaps the proponents could point
> us to example documents in each format used to format a manual?

Well, I'm not really advocating replacing Texinfo, so I'm off the hook
there.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Lars Magne Ingebrigtsen <larsi@gnus.org>
> Date: Wed, 10 Dec 2014 09:28:01 +0100
> Cc: emacs-devel@gnu.org
> 
> Yes.  The way the Texinfo maintainers dropped the ball here is perhaps
> the best argument (so far) for why Emacs should switch to a different
> input format.

Definitely not convincing enough for me.

How about if all of you started complaining on bug-texinfo about the
speed (or, rather, lack thereof)?

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Wed, 10 Dec 2014 03:40:46 -0600
> 
> Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Paul Eggert <eggert@cs.ucla.edu> writes:
> >
> >> Sometimes it's just one Emacs manual, but often enough I'm editing
> >> multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is
> >> still waayyy toooo sloooowww.
> >
> > Texinfo 4 is still available, isn't it?  
> 
> Not in Cygwin, which is where I get texinfo for Windows.

If it doesn't _have_ to be Cygwin, you will find both Texinfo 4.13a
and 5.2 here:

  https://sourceforge.net/projects/ezwinports/files/?source=navbar

Re: On being web-friendly and why info must die

[Paul Eggert]

Eli Zaretskii wrote:
> How about if all of you started complaining on bug-texinfo about the
> speed (or, rather, lack thereof)?

We did that right away, when we first discovered the performance problem.  But 
the bug is neither easily fixed nor likely to get fixed, and its persistence 
will continue to discourage contributions to GNU documentation.

Re: On being web-friendly and why info must die

[Stephen Leake]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> On 12/09/2014 02:00 PM, Lars Magne Ingebrigtsen wrote:
>>> Texinfo 4 is still available, isn't it?  I can't recall whether I
>>> installed it myself or it was just there, but I found Texinfo 5
>>> unbearable and switched.
>>
>> And that's a problem.  The fact that so many core Emacs contributors
>> stick with Texinfo 4 is not only a technical problem (Texinfo 4
>> doesn't check syntax typos as well, it is still quoting 1970s-style,
>> etc.), it's a marketing problem as we're giving potential contributors
>> the impression that our development process has ossified.
>
> Yes.  The way the Texinfo maintainers dropped the ball here is perhaps
> the best argument (so far) for why Emacs should switch to a different
> input format.

I agree it's the strongest argument; I also agree with Eli that it's not
strong enough.

I'd be happy to help rewrite texinfo in Ada (which I realize is a free
offer, since it's a non-starter :).

On the other hand, I just built emacs.info after changing one file. The
make time was noticable, but no longer than other make times I encounter
daily.

I have a fairly fast machine; about three years old, 4 core 2.4 GHz,
Windows 7.

-- 
-- Stephe

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Wed, 10 Dec 2014 09:09:58 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> > How about if all of you started complaining on bug-texinfo about the
> > speed (or, rather, lack thereof)?
> 
> We did that right away, when we first discovered the performance problem.

I know, I was there ;-)

What I meant was to keep complaining.

> But the bug is neither easily fixed nor likely to get fixed, and its
> persistence will continue to discourage contributions to GNU
> documentation.

Things change with time.  What looked improbable then might be less
improbable now.  If nothing else, one or two active contributors to
Texinfo came on board since then; perhaps one of them will pick up the
gauntlet.

Re: On being web-friendly and why info must die

[Kyle Andrews]

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

John Kitchin wrote a GFDL licensed book on Density Functional Theory (a
computationally efficient way of computing many quantum mechanical
properties of materials) in Org mode.

https://github.com/jkitchin/dft-book

On Wednesday, December 10, 2014, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Here is an example-based walkthrough of a subset of the format:
>   >  http://steinar.bang.priv.no/2012/05/02/using-org-mode/
>
> This expains how to use Org mode to edit outlines, track times, and
> other things that are not particularly useful for me.
>
> It does not explain how to use Org format to format a manual.
>
> --
> Dr Richard Stallman
> President, Free Software Foundation
> 51 Franklin St
> Boston MA 02110
> USA
> www.fsf.org  www.gnu.org
> Skype: No way! That's nonfree (freedom-denying) software.
>   Use Ekiga or an ordinary phone call.
>
>
>

[-- Attachment #2: Type: text/html, Size: 1599 bytes --]

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/10/2014 01:38 AM, Stephen Leake wrote:
> One workaround while waiting for a faster makeinfo; keep branches in
> separate workspaces.

Yes, and I do that.  But this is more complexity, which is an obstacle 
to contributing to Emacs.  Emacs has a lot of cruft that discourages 
contributions, and we should be streamlining it whenever possible.

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/10/2014 01:01 AM, David Kastrup wrote:

> it's probably half a minute of the overall compile time.

On my 3-year-old desktop 'make' takes one minute and four seconds merely 
to generate info/elisp.info (no image processing is involved).  That's 
really off-putting.  Even half a minute would be too long.

> For projects external to GNU, we may or may not
> even have the possibility to spend time/effort for making them better
> suited for GNU.

If we use free formats and software for our documentation, this should 
not be a real problem.  In the worst case we could fork the software 
ourselves, though obviously we'd rather not have to resort to that.  
Emacs development already relies on projects external to GNU, and this 
would be just one more instance -- although it's not something we'd do 
without thinking about it, it's also not something we'd reject merely 
because it's non-GNU.

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/10/2014 10:04 AM, Eli Zaretskii wrote:
> Things change with time.  What looked improbable then might be less
> improbable now.

Please feel free to keep complaining to the Texinfo developers.  You 
might even point them at this thread.  To be honest, though, I'm not 
optimistic about Texinfo performance improving any time soon.

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On my 3-year-old desktop 'make' takes one minute and four seconds
> merely to generate info/elisp.info (no image processing is involved).
> That's really off-putting.  Even half a minute would be too long.

Is there a format out there that does not require to be compiled to
check the correctness of the changes? If the text editor is smart enough
to make obvious (or impossible) the common problems, there is no
pressing need to check the final result for each change.

Editing Org documents in Emacs comes to mind.

Re: On being web-friendly and why info must die

[Jay Belanger]

> John Kitchin wrote a GFDL licensed book on Density Functional Theory
> (a computationally efficient way of computing many quantum mechanical
> properties of materials) in Org mode.

Which is cool, but doesn't say how to write a manual in org mode.
Neither does mentioning a few pages in the middle of a long manual.

Is it feasible to have another program, besides texinfo, produce info
documents?  For example, could org be converted to info directly?

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/10/2014 11:18 AM, Óscar Fuentes wrote:
> If the text editor is smart enough
> to make obvious (or impossible) the common problems, there is no
> pressing need to check the final result for each change.

That should catch some problems, but it's not enough.  Typically I focus 
on that editing the .texi file first to get the content right.  Then, I 
want to make sure the result is readable so I generate the output and 
look at it.  Problems with looks often include fairly-mundane things 
like a capitalized word at sentence end which messes up later spacing, 
things which one can easily see when looking at the info output, but 
which one can't easily expect a text editor to catch.

RE: On being web-friendly and why info must die

[Phillip Lord]

Way back, Achim Gratz posted a link to the port of the org-manual
to org-mode.

http://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00561.html

This clearly does show (by example) how to write a manual in org-mode. That post also 
explains the difficulties with doing this (i.e. the performance sucks).

Org-mode doesn't export to info (directly) at the moment. AFAICT, through info 
is simpler than texinfo, so there is no reason that it shouldn't be made to (at least once the 
current changes in the exported infrastructure are complete).

The advantage from a point of view of the author with org is that a significant amount of the functionality
of org-mode export (i.e. hyperlinks and the like) also works inside org-mode. So you can test it at source 
level. It would imagine some people would also be quite happy using org-mode as a replacement for info.
After all, headers and the like all work, navigation is quite functional.

Just a thought.

________________________________________
From: emacs-devel-bounces+phillip.lord=newcastle.ac.uk@gnu.org [emacs-devel-bounces+phillip.lord=newcastle.ac.uk@gnu.org] on behalf of Jay Belanger [jay.p.belanger@gmail.com]
Sent: 10 December 2014 19:18
To: emacs-devel@gnu.org
Cc: jay.p.belanger@gmail.com
Subject: Re: On being web-friendly and why info must die

> John Kitchin wrote a GFDL licensed book on Density Functional Theory
> (a computationally efficient way of computing many quantum mechanical
> properties of materials) in Org mode.

Which is cool, but doesn't say how to write a manual in org mode.
Neither does mentioning a few pages in the middle of a long manual.

Is it feasible to have another program, besides texinfo, produce info
documents?  For example, could org be converted to info directly?

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Paul Eggert <eggert@cs.ucla.edu> writes:

> That should catch some problems, but it's not enough.  Typically I
> focus on that editing the .texi file first to get the content right.
> Then, I want to make sure the result is readable so I generate the
> output and look at it.

I reckon that those issues are related to the texinfo format,
specifically. Other formats can be checked for readability without
exporting them first.

> Problems with looks often include
> fairly-mundane things like a capitalized word at sentence end which
> messes up later spacing, things which one can easily see when looking
> at the info output, but which one can't easily expect a text editor to
> catch.

Isn't it possible to defer those issues to an advanced stage where the
areas with documentation changes are checked ``en-masse'' instead of
checking one change at a time?

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Wed, 10 Dec 2014 20:47:21 +0100
> 
> > Problems with looks often include
> > fairly-mundane things like a capitalized word at sentence end which
> > messes up later spacing, things which one can easily see when looking
> > at the info output, but which one can't easily expect a text editor to
> > catch.
> 
> Isn't it possible to defer those issues to an advanced stage where the
> areas with documentation changes are checked ``en-masse'' instead of
> checking one change at a time?

If you push unchecked changes, and they cause errors, you might
confuse people or even break the build.  So I always generate the docs
before committing any documentation changes, even the smallest ones.

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

> If you push unchecked changes, and they cause errors, you might
> confuse people or even break the build.  So I always generate the docs
> before committing any documentation changes, even the smallest ones.

I was talking on the context of a doc format that allows Emacs to help
the writer to reduce errors to a rare event.

Re: On being web-friendly and why info must die

[Paul Eggert]

On 12/10/2014 11:47 AM, Óscar Fuentes wrote:
> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> Typically I
>> focus on that editing the .texi file first to get the content right.
>> Then, I want to make sure the result is readable so I generate the
>> output and look at it.
> I reckon that those issues are related to the texinfo format,
> specifically. Other formats can be checked for readability without
> exporting them first.

Sorry, I'm lost.  To me, "texinfo format" is the format of (say) 
doc/lispref/intro.texi.  But I can check that for readability as I edit 
it.  The problem is that I also need to check the info-format output, 
which is in info/elisp.info.  To do that, I need to run 'makeinfo', 
which takes over a minute on my machine.

True, I can often just as easily check the HTML output of 'makeinfo' 
instead.  But the HTML takes even longer to generate than the info 
output does (78 seconds as opposed to 64 seconds on my machine), so 
that's not a realistic alternative.

> Isn't it possible to defer those issues to an advanced stage where the 
> areas with documentation changes are checked ``en-masse'' instead of 
> checking one change at a time? 

That's less efficient.  When I'm making a change I'm conscious of it and 
can check it easily.  If I (or worse, someone else) checks it several 
months later, it'll take them more time to get into the swing of things.

More generally, it's not good practice for Emacs developers to check in 
poorly-documented changes, and expect this to get fixed en masse later 
in a documentation pass.  It's better if a change results in a coherent 
Emacs (code, documentation, tests, etc.) and is installed all at once 
(perhaps as a merge commit).  I realize this isn't always possible, but 
still it's a good goal.  Also, I realize that this policy hasn't always 
been a goal in Emacs development, but that's something I'd like to see 
changed as we move forward.

Re: On being web-friendly and why info must die

[Óscar Fuentes]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 12/10/2014 11:47 AM, Óscar Fuentes wrote:
>> Paul Eggert <eggert@cs.ucla.edu> writes:
>>
>>> Typically I
>>> focus on that editing the .texi file first to get the content right.
>>> Then, I want to make sure the result is readable so I generate the
>>> output and look at it.
>> I reckon that those issues are related to the texinfo format,
>> specifically. Other formats can be checked for readability without
>> exporting them first.
>
> Sorry, I'm lost.  To me, "texinfo format" is the format of (say)
> doc/lispref/intro.texi.  But I can check that for readability as I
> edit it.  The problem is that I also need to check the info-format
> output, which is in info/elisp.info.  To do that, I need to run
> 'makeinfo', which takes over a minute on my machine.
>
> True, I can often just as easily check the HTML output of 'makeinfo'
> instead.  But the HTML takes even longer to generate than the info
> output does (78 seconds as opposed to 64 seconds on my machine), so
> that's not a realistic alternative.

Some formats (like Org) are "final", in the sense that the source text
(the equivalent of *.texi) is intended for consumption (it is the *.info
too, although not as pretty as some of its other representations such as
HTML.) Failures on the structure are visible, links can be checked right
away, etc. Hence, revising one of those alternative representations of
the Org document makes as much sense as revising *both* the .info and
.html products of the source .texi: it is ok for checking aesthetic
details, but overkill as a means of checking the correctness of the
*.texi itself.

>> Isn't it possible to defer those issues to an advanced stage where
>> the areas with documentation changes are checked ``en-masse''
>> instead of checking one change at a time? 
>
> That's less efficient.  When I'm making a change I'm conscious of it
> and can check it easily.  If I (or worse, someone else) checks it
> several months later, it'll take them more time to get into the swing
> of things.

There are several aspects of correctness which affects the *who* and the
*when*:

1. the author of the change shall convey the information on the
   documentation.

2. checking the resulting document in terms of appearance criteria can
   be done by another individual.

3. checking the resulting document in terms of clarity, completeness,
   style, etc. *must* be done by someone who is not the author.

For you as the author, it is a good thing to do 1 ASAP. If the
documentation tool allows you to do the job without "building the docs"
to check that you didn't break the build, etc., you stop caring about
the speed of that process.

But we can delay 2 and 3 until a late stage of the development cycle.
This avoids re-testing the same areas as they are successively touched
by changes, but makes even more sense because documentation is expected
to be a coherent corpus, something you can't check when you test the
changes as soon as they are introduced.

> More generally, it's not good practice for Emacs developers to check
> in poorly-documented changes, and expect this to get fixed en masse
> later in a documentation pass.

No, that's not what I was proposing at all.

> It's better if a change results in a
> coherent Emacs (code, documentation, tests, etc.) and is installed all
> at once (perhaps as a merge commit).  I realize this isn't always
> possible, but still it's a good goal.  Also, I realize that this
> policy hasn't always been a goal in Emacs development, but that's
> something I'd like to see changed as we move forward.

Yes, as I mentioned on other message (thread?) requiring documentation
with the code change is something that would increase the quality of
Emacs and shorten the release cycles (which makes the project more
attractive for contributors as well; when one hacker makes a
contribution, he probably wishes to see it released before his
retirement.)

Re: On being web-friendly and why info must die

[Paul Eggert]

Óscar Fuentes wrote:

> Some formats (like Org) are "final", in the sense that the source text
> (the equivalent of *.texi) is intended for consumption (it is the *.info
> too, although not as pretty as some of its other representations such as
> HTML.) Failures on the structure are visible, links can be checked right
> away, etc.

This is an advantage of Org mode over Texinfo.

> 3. checking the resulting document in terms of clarity, completeness,
>     style, etc. *must* be done by someone who is not the author.

It's certainly better to have a non-author also check appearance and style.  But 
this doesn't affect the point that it's better when the author can check these 
things easily too, right away when writing the change.  Right now, though, 
Texinfo 5 is making it unnecessarily hard for Emacs documentation authors to 
check their work.

Besides, we need to be realistic: we don't have an army of documentation 
developers and we're unlikely to gain one while our doc tools are more awkward 
than they need to be.  If we stick with our current development process this 
problem will likely just fester.

Would it be reasonable to pick one part of the Emacs manual -- 
doc/misc/org.texi, say -- and convert it to Org mode?  The idea is to see how 
well Org mode would work for representing all of the Emacs documentation, and 
perhaps we can convert it one manual at a time rather than trying to do it all 
at once.

Re: On being web-friendly and why info must die

[David Kastrup]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Óscar Fuentes wrote:
>
>> Some formats (like Org) are "final", in the sense that the source text
>> (the equivalent of *.texi) is intended for consumption (it is the *.info
>> too, although not as pretty as some of its other representations such as
>> HTML.) Failures on the structure are visible, links can be checked right
>> away, etc.
>
> This is an advantage of Org mode over Texinfo.

It's also a disadvantage since it means that one simple text-based
output format has to contain the full information relevant for all other
output formats.  Which causes visual clutter not relevant for the
text-based output format.

I have no idea what you mean by "Failures on the structure are visible"
when one can only see the source text.

> Besides, we need to be realistic: we don't have an army of
> documentation developers and we're unlikely to gain one while our doc
> tools are more awkward than they need to be.  If we stick with our
> current development process this problem will likely just fester.

Again: Texinfo is not a relevant hurdle.  Elisp is.

Org most certainly would be a larger hurdle for me.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 9:54 AM, David Kastrup <dak@gnu.org> wrote:
> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> Óscar Fuentes wrote:
>>
>>> Some formats (like Org) are "final", in the sense that the source text
>>> (the equivalent of *.texi) is intended for consumption (it is the *.info
>>> too, although not as pretty as some of its other representations such as
>>> HTML.) Failures on the structure are visible, links can be checked right
>>> away, etc.
>>
>> This is an advantage of Org mode over Texinfo.
>
> It's also a disadvantage since it means that one simple text-based
> output format has to contain the full information relevant for all other
> output formats.  Which causes visual clutter not relevant for the
> text-based output format.

But for HTML you add style sheets. So it is not really true that the
org format has to contain all the information.

Re: On being web-friendly and why info must die

[Phillip Lord]

David Kastrup <dak@gnu.org> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> Óscar Fuentes wrote:
>>
>>> Some formats (like Org) are "final", in the sense that the source text
>>> (the equivalent of *.texi) is intended for consumption (it is the *.info
>>> too, although not as pretty as some of its other representations such as
>>> HTML.) Failures on the structure are visible, links can be checked right
>>> away, etc.
>>
>> This is an advantage of Org mode over Texinfo.
>
> It's also a disadvantage since it means that one simple text-based
> output format has to contain the full information relevant for all other
> output formats.  Which causes visual clutter not relevant for the
> text-based output format.


The hope would be that this is kept to a minimum. For example, I am
writing a book (using latex) with both a HTML and PDF output. Most of
the conditional logic is in one place (in the prolog). I tried doing
this with org also; again most of the multi format stuff was at the
beginning of the file or in a lisp driver file.

In the end, I stopped using org, and moved to latex because I find that
the cross-referencing and bibliography facilities were better in auctex
than org.

> I have no idea what you mean by "Failures on the structure are visible"
> when one can only see the source text.

Org renders links clickable, and fontifies (and folds) based on the
document structure. If it's broken in the org source, the visual
presentation is also broken in org-mode.

Basically, org-mode is WYSIWIGish.

>> Besides, we need to be realistic: we don't have an army of
>> documentation developers and we're unlikely to gain one while our doc
>> tools are more awkward than they need to be.  If we stick with our
>> current development process this problem will likely just fester.
>
> Again: Texinfo is not a relevant hurdle.  Elisp is.
>
> Org most certainly would be a larger hurdle for me.

Well, lots of people here are saying that texinfo is a problem, even if
it is not for you.

Phil

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 9:54 AM, David Kastrup <dak@gnu.org> wrote:
>> Paul Eggert <eggert@cs.ucla.edu> writes:
>>
>>> Óscar Fuentes wrote:
>>>
>>>> Some formats (like Org) are "final", in the sense that the source text
>>>> (the equivalent of *.texi) is intended for consumption (it is the *.info
>>>> too, although not as pretty as some of its other representations such as
>>>> HTML.) Failures on the structure are visible, links can be checked right
>>>> away, etc.
>>>
>>> This is an advantage of Org mode over Texinfo.
>>
>> It's also a disadvantage since it means that one simple text-based
>> output format has to contain the full information relevant for all other
>> output formats.  Which causes visual clutter not relevant for the
>> text-based output format.
>
> But for HTML you add style sheets. So it is not really true that the
> org format has to contain all the information.

Style sheets contain formatting, not information.  Everything that a
style sheet has to apply to individually needs to be marked with a
corresponding div tag or similar individually.  So I stand by my
statement that the Org format has to contain all the information.  It
does not need to contain specifics about the formatting, such as the
background color, or the fonts/markup for _every_ @file construct.  But
it still needs to mark everything specifically for which a specific
formatting, whether or not specified in a style sheet, is supposed to
apply.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> David Kastrup <dak@gnu.org> writes:
>
>> Again: Texinfo is not a relevant hurdle.  Elisp is.
>>
>> Org most certainly would be a larger hurdle for me.
>
> Well, lots of people here are saying that texinfo is a problem, even
> if it is not for you.

As long as I don't see those "lots of people" offering to contribute
non-marked up manual sections either, it is irrelevant whether they are
saying texinfo is a problem for them.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 12:52 PM, David Kastrup <dak@gnu.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>>>
>>> It's also a disadvantage since it means that one simple text-based
>>> output format has to contain the full information relevant for all other
>>> output formats.  Which causes visual clutter not relevant for the
>>> text-based output format.
>>
>> But for HTML you add style sheets. So it is not really true that the
>> org format has to contain all the information.
>
> Style sheets contain formatting, not information.  Everything that a
> style sheet has to apply to individually needs to be marked with a
> corresponding div tag or similar individually.  So I stand by my
> statement that the Org format has to contain all the information.  It
> does not need to contain specifics about the formatting, such as the
> background color, or the fonts/markup for _every_ @file construct.  But
> it still needs to mark everything specifically for which a specific
> formatting, whether or not specified in a style sheet, is supposed to
> apply.

That is true of course, but it can be fixed. (You could add hidden
tags to the org format. I do not know how if that is possible now.
Adding some JSON tags could perhaps be an alternative.)

But the point I (and I believe others) are trying to make is that with
org-mode you can start simple. And it is still useful. And perhaps,
perhaps, org-format could be made to carry the needed information.
(Not sure about that, though!)

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> But the point I (and I believe others) are trying to make is that with
> org-mode you can start simple.

Uh, are we still talking about Texinfo?  You won't be using more than
about a dozen commands regularly.  This is not plain TeX.  It isn't even
LaTeX.  It's a boringly stupid and limited markup language that takes
very little effort to learn and also is easily recognizable and workable
just copying the skeleton of existing files.

> And it is still useful. And perhaps, perhaps, org-format could be made
> to carry the needed information.  (Not sure about that, though!)

Sorry, but I don't buy the argument about Texinfo's complexity.  And the
kind of "I won't touch what I am not previously accustomed to, no matter
how simple" hypothetical documentation contributors we are talking about
will not be writing substantial amounts of documentation for something
as big and complex as Emacs.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Phillip Lord]

David Kastrup <dak@gnu.org> writes:

> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>
>> David Kastrup <dak@gnu.org> writes:
>>
>>> Again: Texinfo is not a relevant hurdle.  Elisp is.
>>>
>>> Org most certainly would be a larger hurdle for me.
>>
>> Well, lots of people here are saying that texinfo is a problem, even
>> if it is not for you.
>
> As long as I don't see those "lots of people" offering to contribute
> non-marked up manual sections either, it is irrelevant whether they are
> saying texinfo is a problem for them.


At the risk of repeating a point that has been made before, yes, of
course it is the case that for the majority of people who are actively
using texinfo to produce documentation for Emacs, texinfo is not a
problem.

The incremental approach, however, of first enabling the use of org so
that some of the documentation could be written using it and then
transforming this to texinfo (to work with the rest of the tool chain)
would be interesting. It would, for example, allow you to see whether
org would be a problem for you in a real environment.

If it works, then the eventual aim could be to throw out texinfo and
replace it with org by simple virtual of writing a org->info exported
(direct rather than through texinfo). Or removing info and using
org->eww usable HTML for in Emacs browsing. Or, supplementing org with a
"kiosk" mode, and just using the org source directly as a viewing
format.

If it doesn't work, then you will have been right all along.

It's the reverse Yoda approach: "try or try not: there is no do".

Phil

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > If you explain exactly what are the features you need to write a manual it
  > will be easier to provide good documentation.

Look at the Texinfo manual to see what features are needed.
Any feature it covers is a job that needs to be done somehow.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > It does not explain how to use Org format to format a manual.

  > There is an example in that Org document for a memo which shows basic
  > document structure, and some formatting (a C code example).  That's what
  > I intended you to see.

Write a manual for formatting manuals in Org format,
and then we could consider it for such use.
It should include all the features of Texinfo format,
or at least come pretty close.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> David Kastrup <dak@gnu.org> writes:
>
>> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>>
>>> David Kastrup <dak@gnu.org> writes:
>>>
>>>> Again: Texinfo is not a relevant hurdle.  Elisp is.
>>>>
>>>> Org most certainly would be a larger hurdle for me.
>>>
>>> Well, lots of people here are saying that texinfo is a problem, even
>>> if it is not for you.
>>
>> As long as I don't see those "lots of people" offering to contribute
>> non-marked up manual sections either, it is irrelevant whether they are
>> saying texinfo is a problem for them.
>
>
> At the risk of repeating a point that has been made before, yes, of
> course it is the case that for the majority of people who are actively
> using texinfo to produce documentation for Emacs, texinfo is not a
> problem.
>
> The incremental approach, however, of first enabling the use of org so
> that some of the documentation could be written using it and then
> transforming this to texinfo (to work with the rest of the tool chain)
> would be interesting. It would, for example, allow you to see whether
> org would be a problem for you in a real environment.

The main reason brought forward for abandoning Texinfo appears that it
has become slower.  So we convert instead to a system that is even
slower in order to indirectly produce Texinfo which we will then
_additionally_ convert to Info?

> If it works, then the eventual aim could be to throw out texinfo and
> replace it with org by simple virtual of writing a org->info exported
> (direct rather than through texinfo).

Would still be slower than now, correct?

> Or removing info and using org->eww usable HTML for in Emacs
> browsing.

Except that eww is a very basic browser, and not even the non-basic
browsers for HTML are even remotely comparable in performance and
usability to Emacs' Info browser.  And the HTML format cannot support
full-document search from a single-page display on principle.

> Or, supplementing org with a "kiosk" mode, and just using the org
> source directly as a viewing format.
>
> If it doesn't work, then you will have been right all along.

So far, I don't see anything that would ultimately address the perceived
problems.

> It's the reverse Yoda approach: "try or try not: there is no do".

Yes, I understood that this is all about hipsterisms.  But hip does not
get the work done or redone.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Ludovic Courtès]

GNU has a culture of high-quality documentation.  Texinfo is a tool for
that, providing features like indexes, cross-manual references,
documentation-oriented markup, and several output media.  AFAIK, neither
AsciiDoc nor “heavier” options like DocBook support all of that.

Info browsers make it easy to browse manuals, search for index terms,
follow links, including to other manuals.  A Web browser cannot achieve
that because a Web browser is not designed for that.

"Eric S. Raymond" <esr@thyrsus.com> skribis:

> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.

That’s a discussion that would need to involve all of GNU, not just
Emacs circles.  I don’t see how that change could happen.

IMO we should think about what makes sense to achieve the project’s
goals, and set the standards rather than wander around to please the
hypothetical “younger developers.”

Ludo’.

Re: Alternative input formats

[Ludovic Courtès]

Richard Stallman <rms@gnu.org> skribis:

> If we develop software to browse HTML manuals made by Texifo with all
> the good features of info, then we can drop use of Info format.

But HTML itself lacks the notion of indexes or cross-manual references,
for instance (cross-manual references must work both with on-line copies
and with locally installed manuals.)

Ludo’.

Re: On being web-friendly and why info must die

[Ted Zlatanov]

On Thu, 11 Dec 2014 15:27:58 +0100 ludo@gnu.org (Ludovic Courtès) wrote: 

LC> IMO we should think about what makes sense to achieve the project’s
LC> goals, and set the standards rather than wander around to please the
LC> hypothetical “younger developers.”

You're setting up those two as if they are exclusive.

Ted "hypothetically younger"

Re: On being web-friendly and why info must die

[Phillip Lord]

David Kastrup <dak@gnu.org> writes:
>> At the risk of repeating a point that has been made before, yes, of
>> course it is the case that for the majority of people who are actively
>> using texinfo to produce documentation for Emacs, texinfo is not a
>> problem.
>>
>> The incremental approach, however, of first enabling the use of org so
>> that some of the documentation could be written using it and then
>> transforming this to texinfo (to work with the rest of the tool chain)
>> would be interesting. It would, for example, allow you to see whether
>> org would be a problem for you in a real environment.
>
> The main reason brought forward for abandoning Texinfo appears that it
> has become slower.  So we convert instead to a system that is even
> slower in order to indirectly produce Texinfo which we will then
> _additionally_ convert to Info?


The main reason *that you accept* for moving from texinfo yes. There are
other reasons also. Yes, it would be slower.


>> If it works, then the eventual aim could be to throw out texinfo and
>> replace it with org by simple virtual of writing a org->info exported
>> (direct rather than through texinfo).
>
> Would still be slower than now, correct?


It's not possible to tell, since direct org->info does not exist. I
suspect perl text hacking is quicker than emacs lisp hacking, but
texinfo and org are different input formats.

Having said that, if viewing the documentation is org-mode is enough to
be happy that it is correct, and this becomes a batch process then the
speed becomes less relevant.


>> Or removing info and using org->eww usable HTML for in Emacs
>> browsing.
>
> Except that eww is a very basic browser, and not even the non-basic
> browsers for HTML are even remotely comparable in performance and
> usability to Emacs' Info browser.  And the HTML format cannot support
> full-document search from a single-page display on principle.

This has also been discussed at length, of course. Personally, I am
dubious about the value of having two hypertext browsers integrated into
Emacs. I agree that info indexing and bookstyle (next, back) browsing is
better than an arbitrary browser. But if the document structure were
exported to XML, then this support could be added to EWW. If you wanted,
the same trick and some javascript work give the same navigation
capabilities as info to any webpage.



>> Or, supplementing org with a "kiosk" mode, and just using the org
>> source directly as a viewing format.
>>
>> If it doesn't work, then you will have been right all along.
>
> So far, I don't see anything that would ultimately address the perceived
> problems.


No, I realise that.

>
>> It's the reverse Yoda approach: "try or try not: there is no do".
>
> Yes, I understood that this is all about hipsterisms.  But hip does not
> get the work done or redone.

I am saddened that my humour witticisms have not lightened your day. I
will try and do harder. A discussion about text formats for manual
pages is not natural territory for gags.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Ludovic Courtès <ludo@gnu.org> writes:
> GNU has a culture of high-quality documentation.  Texinfo is a tool for
> that, providing features like indexes, cross-manual references,
> documentation-oriented markup, and several output media.  AFAIK, neither
> AsciiDoc nor “heavier” options like DocBook support all of that.

Asiidoc does do indexes, as does docbook. And, yes, multiple output
formats. Seriously, almost everything does multiple output formats.

> Info browsers make it easy to browse manuals, search for index terms,
> follow links, including to other manuals.  A Web browser cannot achieve
> that because a Web browser is not designed for that.

Web pages and browsers can do anything at all. Here is a webpage which boots
so linux and runs some of GNU

http://jslinux.org/

I use a web browser as powerpoint presentation tool, complete with next
and back buttons, timers and index navigation. I don't think anyone has
done it yet, but you could port info to a browser if you wanted.



> "Eric S. Raymond" <esr@thyrsus.com> skribis:
>
>> I have discussed this with RMS and, pending my ability to actually write
>> proper translation tools, we have agreed on asciidoc as a new master 
>> format.
>
> That’s a discussion that would need to involve all of GNU, not just
> Emacs circles.  I don’t see how that change could happen.

Not really. Someone has to try it first.


Phil

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> David Kastrup <dak@gnu.org> writes:
>>> At the risk of repeating a point that has been made before, yes, of
>>> course it is the case that for the majority of people who are actively
>>> using texinfo to produce documentation for Emacs, texinfo is not a
>>> problem.
>>>
>>> The incremental approach, however, of first enabling the use of org so
>>> that some of the documentation could be written using it and then
>>> transforming this to texinfo (to work with the rest of the tool chain)
>>> would be interesting. It would, for example, allow you to see whether
>>> org would be a problem for you in a real environment.
>>
>> The main reason brought forward for abandoning Texinfo appears that it
>> has become slower.  So we convert instead to a system that is even
>> slower in order to indirectly produce Texinfo which we will then
>> _additionally_ convert to Info?
>
>
> The main reason *that you accept* for moving from texinfo yes. There are
> other reasons also. Yes, it would be slower.
>
>
>>> If it works, then the eventual aim could be to throw out texinfo and
>>> replace it with org by simple virtual of writing a org->info exported
>>> (direct rather than through texinfo).
>>
>> Would still be slower than now, correct?
>
>
> It's not possible to tell, since direct org->info does not exist. I
> suspect perl text hacking is quicker than emacs lisp hacking, but
> texinfo and org are different input formats.

Well, easy to compare "perl text hacking" with "emacs lisp hacking":
just compare the execution speeds of M-x makeinfo-buffer RET (Perl text
hacking when makeinfo is version 5.x) with M-x texinfo-format-buffer RET
(should be Elisp).

>>> It's the reverse Yoda approach: "try or try not: there is no do".
>>
>> Yes, I understood that this is all about hipsterisms.  But hip does
>> not get the work done or redone.
>
> I am saddened that my humour witticisms have not lightened your day.

The sun tends to do a better job with that.

> I will try and do harder.

Can we focus on the best arguments rather than the best movie insider
jokes?  Working on free software does not really leave much of a budget
for cinema for me, so I prefer not to compete in that area.

> A discussion about text formats for manual pages is not natural
> territory for gags.

That is a feature, not a bug.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> "Eric S. Raymond" <esr@thyrsus.com> skribis:
>>
>>> I have discussed this with RMS and, pending my ability to actually write
>>> proper translation tools, we have agreed on asciidoc as a new master 
>>> format.
>>
>> That’s a discussion that would need to involve all of GNU, not just
>> Emacs circles.  I don’t see how that change could happen.
>
> Not really. Someone has to try it first.

Arguably Emacs is the absolutely worst-suited project "to try it first"
since Emacs users have the absolutely best Info browser at their hands,
and possibly the best Texinfo editing modes, while having pretty poor
support for other source formats.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lennart Borgman]

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

On Thu, Dec 11, 2014 at 4:23 PM, David Kastrup <dak@gnu.org> wrote:
> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>>
> Arguably Emacs is the absolutely worst-suited project "to try it first"
> since Emacs users have the absolutely best Info browser at their hands,
> and possibly the best Texinfo editing modes, while having pretty poor
> support for other source formats.

The support for Org format is pretty good. ;-)

[-- Attachment #2: Type: text/html, Size: 706 bytes --]

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 3:27 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>
> GNU has a culture of high-quality documentation.  Texinfo is a tool for
> that, providing features like indexes, cross-manual references,
> documentation-oriented markup, and several output media.  AFAIK, neither
> AsciiDoc nor “heavier” options like DocBook support all of that.
>
> Info browsers make it easy to browse manuals, search for index terms,
> follow links, including to other manuals.  A Web browser cannot achieve
> that because a Web browser is not designed for that.


Not by itself, but with a good search engine it could. I am just
testing http://www.opensearchserver.com/ and I am surprised by the
quality and the easy of use - even locally. (Though to use it locally
you need Java. But the setup is just copying one file. A web server is
builtin.)

Here is test page I have just written:
https://dl.dropboxusercontent.com/u/848981/it/oss/zosspx.html

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 4:23 PM, David Kastrup <dak@gnu.org> wrote:
>> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>>
>>> Ludovic Courtès <ludo@gnu.org> writes:
>>>
>> Arguably Emacs is the absolutely worst-suited project "to try it
>> first" since Emacs users have the absolutely best Info browser at
>> their hands, and possibly the best Texinfo editing modes, while
>> having pretty poor support for other source formats.
>
> The support for Org format is pretty good. ;-)

Admittedly Org can't realistically hope to get better conditions for a
Texinfo/Org shootout than on Emacs.  A mixed blessing.

If you can't make it there, you can't make it anywhere.  It's up to you,
Emacs, Emacs.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Thu, 11 Dec 2014 11:50:11 +0000
> Cc: emacs-devel@gnu.org
> 
> > I have no idea what you mean by "Failures on the structure are visible"
> > when one can only see the source text.
> 
> Org renders links clickable, and fontifies (and folds) based on the
> document structure. If it's broken in the org source, the visual
> presentation is also broken in org-mode.

makeinfo does a lot more validations than that, so David's comment is
still valid.

> Well, lots of people here are saying that texinfo is a problem, even if
> it is not for you.

Most of them don't work on Emacs documentation.  Opinions of those who
do are more important.

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 3:27 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>>
>> GNU has a culture of high-quality documentation.  Texinfo is a tool for
>> that, providing features like indexes, cross-manual references,
>> documentation-oriented markup, and several output media.  AFAIK, neither
>> AsciiDoc nor “heavier” options like DocBook support all of that.
>>
>> Info browsers make it easy to browse manuals, search for index terms,
>> follow links, including to other manuals.  A Web browser cannot achieve
>> that because a Web browser is not designed for that.
>
>
> Not by itself, but with a good search engine it could.

Not really.  Try an incremental full text search through the entire Info
file.  Try jumping through the references for some index term.

The best search engine does not give you a user interface for that kind
of stuff.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Lennart Borgman <lennart.borgman@gmail.com>
> Date: Thu, 11 Dec 2014 13:07:18 +0100
> Cc: Emacs-Devel devel <emacs-devel@gnu.org>
> 
> But the point I (and I believe others) are trying to make is that with
> org-mode you can start simple.

We are not starting the Emacs documentation.  It already exists, and
weighs in at many hundreds of pages.

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 5:14 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Lennart Borgman <lennart.borgman@gmail.com>
>>
>> But the point I (and I believe others) are trying to make is that with
>> org-mode you can start simple.
>
> We are not starting the Emacs documentation.  It already exists, and
> weighs in at many hundreds of pages.

Sorry if I was misunderstanding that. ;-)

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 5:12 PM, David Kastrup <dak@gnu.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>>> Info browsers make it easy to browse manuals, search for index terms,
>>> follow links, including to other manuals.  A Web browser cannot achieve
>>> that because a Web browser is not designed for that.
>>
>>
>> Not by itself, but with a good search engine it could.
>
> Not really.  Try an incremental full text search through the entire Info
> file.  Try jumping through the references for some index term.
>
> The best search engine does not give you a user interface for that kind
> of stuff.

You have to work a bit differently, but that does not mean it is not
just as useful.

My point is maybe a bit unclear. It matters a lot what search engine
you have and how you feed it with information. In the small project I
linked to I have had rather minimal success with Google CSE. So I
switched to OpenSearchServer and there I can do a lot of things I just
could imagine before. (This is just a small free time project, but
still a bit important, perhaps.)

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 5:12 PM, David Kastrup <dak@gnu.org> wrote:
>> Lennart Borgman <lennart.borgman@gmail.com> writes:
>>
>>>> Info browsers make it easy to browse manuals, search for index terms,
>>>> follow links, including to other manuals.  A Web browser cannot achieve
>>>> that because a Web browser is not designed for that.
>>>
>>>
>>> Not by itself, but with a good search engine it could.
>>
>> Not really.  Try an incremental full text search through the entire Info
>> file.  Try jumping through the references for some index term.
>>
>> The best search engine does not give you a user interface for that kind
>> of stuff.
>
> You have to work a bit differently, but that does not mean it is not
> just as useful.

Shrug.  The HTML version of the LilyPond manual has a search box leading
to a search engine.  Results and usage are so far inferior to using
Emacs' info reader that it isn't funny.

> My point is maybe a bit unclear. It matters a lot what search engine
> you have and how you feed it with information. In the small project I
> linked to I have had rather minimal success with Google CSE. So I
> switched to OpenSearchServer and there I can do a lot of things I just
> could imagine before. (This is just a small free time project, but
> still a bit important, perhaps.)

So instead of a working fast local versatile solution, we get some
handwaving promise that some search engines out of our control might do
something different that might be just as good if we really squint in
the right way.

I don't buy that.  It will have its best case scenario for stuff not
actually written/maintained in Texinfo (or something providing similar
information amounts) and consequently completely missing any useful
index.  With that starting point, a search engine is better than
nothing.  Against a reasonably well-maintained manual index, however: no
comparison.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 5:36 PM, David Kastrup <dak@gnu.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>> My point is maybe a bit unclear. It matters a lot what search engine
>> you have and how you feed it with information. In the small project I
>> linked to I have had rather minimal success with Google CSE. So I
>> switched to OpenSearchServer and there I can do a lot of things I just
>> could imagine before. (This is just a small free time project, but
>> still a bit important, perhaps.)
>
> I don't buy that.  It will have its best case scenario for stuff not
> actually written/maintained in Texinfo (or something providing similar
> information amounts) and consequently completely missing any useful
> index.  With that starting point, a search engine is better than
> nothing.  Against a reasonably well-maintained manual index, however: no
> comparison.

I don't understand your argument. What has the well-maintained manual
index to do with the format the user sees? The index just does not
disappear if you are using a web browser. Or, does it? ;-)

Re: On being web-friendly and why info must die

[Ludovic Courtès]

phillip.lord@newcastle.ac.uk (Phillip Lord) skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>> GNU has a culture of high-quality documentation.  Texinfo is a tool for
>> that, providing features like indexes, cross-manual references,
>> documentation-oriented markup, and several output media.  AFAIK, neither
>> AsciiDoc nor “heavier” options like DocBook support all of that.
>
> Asiidoc does do indexes, as does docbook. And, yes, multiple output
> formats. Seriously, almost everything does multiple output formats.

OK.  What about documentation-oriented markup (think @deffn, @deftp) and
cross-manual references?  They don’t do that, do they?

>> Info browsers make it easy to browse manuals, search for index terms,
>> follow links, including to other manuals.  A Web browser cannot achieve
>> that because a Web browser is not designed for that.
>
> Web pages and browsers can do anything at all. Here is a webpage which boots
> so linux and runs some of GNU

I’ve heard of JavaScript, thank you ;-), but I’d rather (1) run code
that’s hosted locally, and (2) be able to use a JS-less browser if I
have to use a browser at all (I think it’s fair to assume that some
Emacs users would rather use emacs-w3m or eww.)

>> "Eric S. Raymond" <esr@thyrsus.com> skribis:
>>
>>> I have discussed this with RMS and, pending my ability to actually write
>>> proper translation tools, we have agreed on asciidoc as a new master 
>>> format.
>>
>> That’s a discussion that would need to involve all of GNU, not just
>> Emacs circles.  I don’t see how that change could happen.
>
> Not really. Someone has to try it first.

The problem is that GNU manuals refer to each other, and Texinfo nodes
are part of their public interface, in a way.

Leaving out cross-manual refs would be a big loss for GNU as a project
to develop a coherent system, because manuals would be left isolated.

To me, if replacing Texinfo and/or Info results in loss of functionality
at all, that’s a showstopper.  I’m surprised alternative systems are not
studied with that in mind.

Thanks,
Ludo’.

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 5:36 PM, David Kastrup <dak@gnu.org> wrote:
>> Lennart Borgman <lennart.borgman@gmail.com> writes:
>>
>>> My point is maybe a bit unclear. It matters a lot what search engine
>>> you have and how you feed it with information. In the small project I
>>> linked to I have had rather minimal success with Google CSE. So I
>>> switched to OpenSearchServer and there I can do a lot of things I just
>>> could imagine before. (This is just a small free time project, but
>>> still a bit important, perhaps.)
>>
>> I don't buy that.  It will have its best case scenario for stuff not
>> actually written/maintained in Texinfo (or something providing similar
>> information amounts) and consequently completely missing any useful
>> index.  With that starting point, a search engine is better than
>> nothing.  Against a reasonably well-maintained manual index, however: no
>> comparison.
>
> I don't understand your argument. What has the well-maintained manual
> index to do with the format the user sees? The index just does not
> disappear if you are using a web browser. Or, does it? ;-)

You were proposing to replace the Info search possibilities with a
search engine.  So it's up to you to explain what you mean.

As for the index not disappearing: it's not accessible from arbitrary
nodes since it is not even loaded into the browser unless you load the
"one big page HTML" and then _all_ navigation becomes cumbersome,
including but not limited to the index.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Thu, 11 Dec 2014 00:06:34 +0100
> 
> 1. the author of the change shall convey the information on the
>    documentation.
> 
> 2. checking the resulting document in terms of appearance criteria can
>    be done by another individual.
> 
> 3. checking the resulting document in terms of clarity, completeness,
>    style, etc. *must* be done by someone who is not the author.
> 
> For you as the author, it is a good thing to do 1 ASAP. If the
> documentation tool allows you to do the job without "building the docs"
> to check that you didn't break the build, etc., you stop caring about
> the speed of that process.

As I wrote elsewhere, I don't see how a tool can do that without
performing most of the job done by makeinfo.  Without that, invalid
cross-references and node prev/next/up pointers might be left
incorrect.  And don't forget pointers to other manuals,

> But we can delay 2 and 3 until a late stage of the development cycle.

This means the development version is incomplete for most of the
time.  Yes, we have this now, but I hope to change that.  Since many
distributions provide snapshots of Emacs, we should strive to have our
docs in good shape at all times.

I also have hard time to imagine we will find volunteers for 2: it's a
mundane, boring job that no one is motivated to do except the author.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Wed, 10 Dec 2014 15:49:32 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> Would it be reasonable to pick one part of the Emacs manual -- 
> doc/misc/org.texi, say -- and convert it to Org mode?  The idea is to see how 
> well Org mode would work for representing all of the Emacs documentation, and 
> perhaps we can convert it one manual at a time rather than trying to do it all 
> at once.

Good idea, IMO.  Any takers?

Re: On being web-friendly and why info must die

[Achim Gratz]

Eli Zaretskii writes:
>> Would it be reasonable to pick one part of the Emacs manual -- 
>> doc/misc/org.texi, say -- and convert it to Org mode?  The idea is to see how 
>> well Org mode would work for representing all of the Emacs documentation, and 
>> perhaps we can convert it one manual at a time rather than trying to do it all 
>> at once.
>
> Good idea, IMO.  Any takers?

The idea is good enough that it has already been done and mentioned at
least three times in this very thread, with links to the result.  Since
nobody seems to have looked at it, here's the Introduction from that Org
manual in Org for your perusal.  If you look at it in Gnus it might even
use org-mode for display.

--8<---------------cut here---------------start------------->8---
* Introduction
  :PROPERTIES:
  :TITLE: Introduction
  :DESCRIPTION: Getting started
  :END:
{{{cindex(introduction)}}}

** Summary
   :PROPERTIES:
   :DESCRIPTION: Brief summary of what Org-mode does
   :END:
{{{cindex(summary)}}}

Org is a mode for keeping notes, maintaining TODO lists, and doing
project planning with a fast and effective plain-text system.

Org develops organizational tasks around NOTES files that contain
lists or information about projects as plain text. Org is implemented
on top of Outline mode, which makes it possible to keep the content of
large files well structured. Visibility cycling and structure editing
help to work with the tree. Tables are easily created with a built-in
table editor. Org supports TODO items, deadlines, timestamps, and
scheduling. It dynamically compiles entries into an agenda that
utilizes and smoothly integrates much of the Emacs calendar and diary.
Plain text URL-like links connect to websites, emails, Usenet
messages, BBDB entries, and any files related to the projects. For
printing and sharing notes, an Org file can be exported as a
structured ASCII file, as HTML, or as an iCalendar file.[fn:1]  It can
also serve as a publishing tool for a set of linked web pages.

As a project planning environment, Org works by adding metadata to
outline nodes. Based on this data, specific entries can be extracted
in queries and create dynamic /agenda views/.

Org mode contains the Org Babel environment which allows you to work
with embedded source code blocks in a file, to facilitate code
evaluation, documentation, and literate programming techniques.

Org's automatic, context-sensitive table editor with spreadsheet
capabilities can be integrated into any major mode by activating the
minor Orgtbl mode. Using a translation step, it can be used to
maintain tables in arbitrary file types, for example in LaTeX. The
structure editing and list creation capabilities can be used outside
Org with the minor Orgstruct mode.

Org keeps simple things simple. When first fired up, it should feel
like a straightforward, easy to use outliner. Complexity is not
imposed, but a large amount of functionality is available when you
need it. Org is a toolbox and can be used in different ways and for
different ends, for example:

  - an outline extension with visibility cycling and structure editing
  - an ASCII system and table editor for taking structured notes
  - a TODO list editor
  - a full agenda and planner with deadlines and work scheduling
    {{{pindex(GTD\\\, Getting Things Done)}}}
  - an environment in which to implement David Allen's GTD system
  - a simple hypertext system, with HTML and LaTeX export
  - a publishing tool to create a set of interlinked web pages
  - an environment for literate programming

{{{cindex(FAQ)}}} 

There is a [[http://orgmode.org][website for Org]] that provides links to the newest version
of Org, as well as additional information, frequently asked questions
(FAQ), links to tutorials, etc.

{{{cindex(print edition)}}} 

Version 7.3 of this manual is available as a [[http://www.network-theory.co.uk/org/manual/][paperback book from
Network Theory Ltd.]]

{{{page}}}

** Installation
   :PROPERTIES:
   :DESCRIPTION: Installing Org
   :END:

{{{cindex(installation)}}}
{{{cindex(XEmacs)}}}

Org is part of recent distributions of GNU Emacs, so you normally don't need
to install it.  If, for one reason or another, you want to install a
different version of Org, there are three ways to do it:

- use the Emacs package system;
- download Org as an archive; or
- use the Org git repository.

We *strongly recommend* that you use only one of these installation
methods.

*** Install from the Emacs package system

Recent Emacs distributions include a packaging system which lets you
install Elisp libraries.  You can install the development version of
Org with {{{kbd(M-x package-install RET org)}}}.  You need to do this
in a session where no {{{file(.org)}}} file has been visited.  Then,
to make sure your Org configuration is taken into account, initialize
the package system with ~(package-initialize)~ in your
{{{file(.emacs)}}} before setting any Org option.  If you want to use
Org's package repository, check out the [[http://orgmode.org/elpa.html][Org ELPA page]].

*** Download Org as an archive

You can download the latest Org release from the [[http://orgmode.org/][Org mode website]],
typically to a location under your home directory.  Optionally, you
can compile the files and/or install them in your system.  Run ~make
help~ to list compilation and installation options.

It is possible to use the latest Org release from the download
location without installing it in your system files.  In this case,
make sure you set the load-path correctly in {{{file(.emacs)}}}:

#+begin_example
     (add-to-list 'load-path "~/path/to/orgdir/lisp")
#+end_example

The downloaded archive contains contributed libraries that are not
included in Emacs.  If you want to use them, add the {{{file(contrib)}}}
directory to your load-path:

#+begin_example
     (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
#+end_example

*** Use the Org git repository

You can clone the development version of the Org git repository,
typically to a location under your home directory.  The example in
this section assumes this location is ~src/~ in your home directory:

#+begin_example
   $ cd ~/src/
   $ git clone git://orgmode.org/org-mode.git
   $ cd org-mode
#+end_example

In most cases where you have permission to write to system locations,
you will probably want to install Org with the Emacs system files.
This is a system-specific operation that is guided by a file,
{{{file(local.mk)}}}, which you must ensure is configured properly.
First, generate a {{{file(local.mk)}}} template with the command ~make
local.mk~.  Edit {{{file(local.mk)}}} following the instructions in
the file, and save it.[fn:185] Check to be sure the build system sees
your changes by running ~make config~.  If all is well, run ~make
install~ to build Org and install it.  The command ~make help~
provides a list of options for the build system.

If you would like to run Org from the clone location, instead of
installing it with the Emacs system files, you can simply run ~make
autoloads~ and set the load-path in your {{{file(.emacs)}}}.
Using the example location, add this to {{{file(.emacs)}}}:

#+begin_example
     (add-to-list 'load-path "~/src/org-mode/lisp")
#+end_example

If your installation has special requirements, please refer to the
detailed description of the capable build system at the [[http://orgmode.org/worg/dev/org-build-system.html][Org Build
System page]].

** Activation
   :PROPERTIES:
   :DESCRIPTION: How to activate Org-mode for certain buffers
   :END:
{{{cindex(activation)}}}
{{{cindex(autoload)}}}
{{{cindex(ELPA)}}}
{{{cindex(global key bindings)}}}
{{{cindex(key bindings\\\, global)}}}
{{{findex(org-agenda)}}}
{{{findex(org-capture)}}}
{{{findex(org-store-link)}}}
{{{findex(org-iswitchb)}}}

Since Emacs 22.2, files with the {{{file(.org)}}} extension use Org mode by
default.  If you are using an earlier version of Emacs, add this line to your
{{{file(.emacs)}}} file:

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
#+end_src

Org mode buffers need font-lock to be turned on: this is the default in
Emacs.[fn:5]

There are compatibility issues between Org mode and some other Elisp
packages, please take the time to check the list (see [[Conflicts]]).

The four Org commands {{{command(org-store-link)}}},
{{{command(org-capture)}}}, {{{command(org-agenda)}}}, and
{{{command(org-iswitchb)}}} should be accessible through global keys
(i.e., anywhere in Emacs, not just in Org buffers).  Here are
suggested bindings for these keys, please modify the keys to your own
liking.

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)
#+end_src

{{{cindex(Org mode\\\, turning on)}}} 
With this setup, all files with extension {{{samp(.org)}}} will be put
into Org mode.  As an alternative, make the first line of a file look
like this:

#+begin_example
   MY PROJECTS    -*- mode: org; -*-
#+end_example

{{{vindex(org-insert-mode-line-in-empty-file)}}} 
{{{noindent}}}
which will select Org mode for this buffer no matter what the file's
name is. See also the variable
~org-insert-mode-line-in-empty-file~.

Many commands in Org work on the region if the region is /active/. To
make use of this, you need to have ~transient-mark-mode~
(~zmacs-regions~ in XEmacs) turned on. In Emacs 23 this is the
default, in Emacs 22 you need to do this yourself with

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(transient-mark-mode 1)
#+end_src

{{{noindent}}} If you do not like ~transient-mark-mode~, you can
create an active region by using the mouse to select a region, or
pressing {{{kbdkey(C-,SPC)}}} twice before moving the cursor.

** Feedback
   :PROPERTIES:
   :DESCRIPTION: Bug reports, ideas, patches, etc.
   :END:
{{{cindex(feedback)}}}
{{{cindex(bug reports)}}}
{{{cindex(maintainer)}}}
{{{cindex(author)}}}

If you find problems with Org, or if you have questions, remarks, or
ideas about it, please mail to the Org mailing list
[[mailto:emacs-orgmode@gnu.org]]. If you are not a member of
the mailing list, your mail will be passed to the list after a
moderator has approved it.[fn:6]

For bug reports, please first try to reproduce the bug with the latest
version of Org available---if you are running an outdated version, it
is quite possible that the bug has been fixed already. If the bug
persists, prepare a report and provide as much information as
possible, including the version information of Emacs ({{{kbdspckey(M-x
emacs-version,RET)}}}) and Org ({{{kbdspckey(M-x org-version,RET)}}}),
as well as the Org related setup in {{{file(.emacs)}}}. The easiest
way to do this is to use the command {{{kbd(M-x
org-submit-bug-report)}}}, which will put all this information into an
Emacs mail buffer so that you only need to add your description. If
you are not sending the Email from within Emacs, please copy and paste
the content into your Email program.

Sometimes you might face a problem due to an error in your Emacs or
Org mode setup.  Before reporting a bug, it is very helpful to start
Emacs with minimal customizations and reproduce the problem.  Doing so
often helps you determine if the problem is with your customization or
with Org mode itself.  You can start a typical minimal session with a
command like the example below.

#+begin_src sh :exports code
$ emacs -Q -l /path/to/minimal-org.el
#+end_src

However if you are using Org mode distributed with Emacs, a minimal
setup is not necessary. In that case it is sufficient to start Emacs
as ~emacs -Q~. The ~minimal-org.el~ setup
file can have contents as shown below.

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
;;; Minimal setup to load latest `org-mode'

;; activate debugging
(setq debug-on-error t
      debug-on-signal nil
      debug-on-quit nil)

;; add latest org-mode to load path
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
#+end_src

If an error occurs, a backtrace can be very useful (see [[How to
create a useful backtrace]]). Often a small example file helps, along
with clear information about:

  1. What exactly did you do?
  2. What did you expect to happen?
  3. What happened instead?

{{{noindent}}} Thank you for helping to improve this program.

** How to create a useful backtrace
   :PROPERTIES:
   :DESCRIPTION: The best way to report an error
   :END:

{{{cindex(backtrace of an error)}}}

If working with Org produces an error with a message you don't
understand, you may have hit a bug.  The best way to report this is by
providing, in addition to what was mentioned above, a /backtrace/.
This is information from the built-in debugger about where and how the
error occurred.  Here is how to produce a useful backtrace:

  1. Reload uncompiled versions of all Org mode Lisp files. The
     backtrace contains much more information if it is produced with
     uncompiled code. To do this, use 
     {{{kbdspckey(C-u M-x org-reload,RET)}}} or select 
     ~Org -> Refresh/Reload -> Reload Org uncompiled~ from the menu.

  2. Go to the ~Options~ menu and select ~Enter Debugger on Error~
     (XEmacs has this option in the ~Troubleshooting~ sub-menu).

  3. Do whatever you have to do to hit the error. Don't forget to
     document the steps you take.

  4. When you hit the error, a {{{file(*Backtrace*)}}} buffer will
     appear on the screen.  Save this buffer to a file (for example
     using {{{kbd(C-x C-w)}}}) and attach it to your bug report.

** Conventions
   :PROPERTIES:
   :DESCRIPTION: Typesetting conventions in the manual
   :END:

Conventions for typesetting keywords, keybindings, and commands in
this manual are described.

*** Three types of keywords
    :PROPERTIES:
    :DESCRIPTION: TODO, tags, and properties
    :END:

Org mainly uses three types of keywords: TODO keywords, tags and property
names.  In this manual we use the following conventions:

  - TODO, WAITING :: TODO keywords are written with all capitals, even if they
    are user-defined.
  - boss, ARCHIVE :: User-defined tags are written in lowercase; built-in
               tags with special meaning are written with all capitals.
  - Release, PRIORITY :: User-defined properties are capitalized; built-in
                properties with special meaning are written with all capitals.

Moreover, Org uses /option keywords/ (like ~#+TITLE~ to set the title)
and /environment keywords/ (like ~#+BEGIN_HTML~ to start a ~HTML~
environment). They are written in uppercase in the manual to enhance
its readability, but you can use lowercase in your Org files.[fn:7]

*** Keybindings and commands
    :PROPERTIES:
    :DESCRIPTION: Bind useful commands to keys
    :END:

{{{kindex(C-c a)}}}
{{{findex(org-agenda)}}}
{{{kindex(C-c c)}}}
{{{findex(org-capture)}}}

The manual suggests two global keybindings: {{{kbd(C-c a)}}} for
~org-agenda~ and {{{kbd(C-c c)}}} for ~org-capture~. These are only
suggestions, but the rest of the manual assumes that you are using
these keybindings.

Also, the manual lists both the keys and the corresponding commands
for accessing a functionality. Org mode often uses the same key for
different functions, depending on context. The command that is bound
to such keys has a generic name, like ~org-metaright~.  In the manual
we will, wherever possible, give the function that is internally
called by the generic command. For example, in the chapter on document
structure, {{{kbdkey(M-,right)}}} will be listed to call
~org-do-demote~, while in the chapter on tables, it will be listed to
call ~org-table-move-column-right~. 

#+comment: If you prefer, you can compile the manual without the command names by unsetting the flag ~cmdnames~ in {{{file(org.texi)}}}.

--8<---------------cut here---------------end--------------->8---


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf Q+, Q and microQ:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > John Kitchin wrote a GFDL licensed book on Density Functional Theory (a
  > computationally efficient way of computing many quantum mechanical
  > properties of materials) in Org mode.

I am glad he did, but in order for Org format to be a usable format
for GNU documentation, it needs to be fully documented.  To be good
for the purpose, this documentation should not be dispersed among
other unrelated topics such as outlines, memos, or time logging.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Some formats (like Org) are "final", in the sense that the source text
  > (the equivalent of *.texi) is intended for consumption (it is the *.info
  > too,

Please don't use the term "consume" to refer to looking at a work.
It's inaccurate because looking at a text doesn't consume it.

What makes that error really significant is that that term is used
to encourage people to adopt a shallow economistic mindset
that supports the propaganda of our enemies.

See http://gnu.org/philosophy/words-to-avoid.html.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Alternative input formats

[Grim Schjetne]

ludo@gnu.org (Ludovic Courtès) writes:

> Richard Stallman <rms@gnu.org> skribis:
>
>> If we develop software to browse HTML manuals made by Texifo with all
>> the good features of info, then we can drop use of Info format.
>
> But HTML itself lacks the notion of indexes or cross-manual references,
> for instance (cross-manual references must work both with on-line copies
> and with locally installed manuals.)

Those notions can be added with something like RDF and JavaScript (the
latter which can indeed be served locally).

My concern is whether it can measure up with the convenience and
consistency of having it as a part of the Emacs UI. I find switching
applications and suddenly being dropped into something that uses
completely different UI conventions quite disruptive.

--
Schjetne

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 8:49 PM, Richard Stallman <rms@gnu.org> wrote:
>
> Please don't use the term "consume" to refer to looking at a work.
> It's inaccurate because looking at a text doesn't consume it.
>
> What makes that error really significant is that that term is used
> to encourage people to adopt a shallow economistic mindset
> that supports the propaganda of our enemies.

Yes, "consume" is a bad word to use here.

But is not "enemy" a bad word too? I think you use it to say those
people believe in other things. Though that does not really make them
enemies IMO.

Using the word "enemy" might make it more difficult to listen to them.
Good ideas comes also from people we do not always agree with. Can we
afford to waste good ideas by not listening at all? (Of course we
should listen critically, but that is another thing. And nothing to
worry about, really. At least not here. ;-) )

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > > 2. checking the resulting document in terms of appearance criteria can
 > >    be done by another individual.

 > I also have hard time to imagine we will find volunteers for 2: it's a
 > mundane, boring job that no one is motivated to do except the author.

Wiki has solved that problem.  That's in the domain of wikis, of
course, but I think it points to hope that Emacs, the *self-documenting*
editor-cum-operating-system-and-Swiss-Army-knife[1] could solve it, too.

Obviously, imagining the volunteers doesn't actually motivate them to
edit and submit, nor provide committers to integrate the changes.  So
I don't think my pipe dream should affect source format decisions in
the short run.


Footnotes: 
[1]  Sorry, David, more out-of-Emacs references. :-)

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Thu, Dec 11, 2014 at 6:20 PM, David Kastrup <dak@gnu.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>> On Thu, Dec 11, 2014 at 5:36 PM, David Kastrup <dak@gnu.org> wrote:
>>> Lennart Borgman <lennart.borgman@gmail.com> writes:
>>>
>>>> My point is maybe a bit unclear. It matters a lot what search engine
>>>> you have and how you feed it with information. In the small project I
>>>> linked to I have had rather minimal success with Google CSE. So I
>>>> switched to OpenSearchServer and there I can do a lot of things I just
>>>> could imagine before. (This is just a small free time project, but
>>>> still a bit important, perhaps.)
>>>
>>> I don't buy that.  It will have its best case scenario for stuff not
>>> actually written/maintained in Texinfo (or something providing similar
>>> information amounts) and consequently completely missing any useful
>>> index.  With that starting point, a search engine is better than
>>> nothing.  Against a reasonably well-maintained manual index, however: no
>>> comparison.
>>
>> I don't understand your argument. What has the well-maintained manual
>> index to do with the format the user sees? The index just does not
>> disappear if you are using a web browser. Or, does it? ;-)
>
> You were proposing to replace the Info search possibilities with a
> search engine.  So it's up to you to explain what you mean.
>
> As for the index not disappearing: it's not accessible from arbitrary
> nodes since it is not even loaded into the browser unless you load the
> "one big page HTML" and then _all_ navigation becomes cumbersome,
> including but not limited to the index.

So that was the argument. OK. ;-)

Yes, without a search engine you can't search the html pages. (Or, you
could build an index in JavaScript, but that is a very tough job if
you want to do something useful.)

Of course you have to search the docs divided into several pages if a
search engine should be of any use. Otherwise you will just get the
same hit all the time. ;-)

OpenSearchServer (based on Apache Lucene) is very flexible. Maybe you
can't get exactly the incremental search that Info uses now, but you
can get a list of suggestions for every character you type. You can
customize that list.

And Info does not have a search capability that is close to the usual
web search (implicit) AND operator.

But there is more you can use, like searching in fields (if the
documents are structured with some fields, of course).

Re: On being web-friendly and why info must die

[Paul Eggert]

Ludovic Courtès wrote:
> if replacing Texinfo and/or Info results in loss of functionality
> at all, that’s a showstopper.

That's too strict.  We should not insist that the new documentation system must 
have every single feature that the old one does.  It should suffice if the new 
system is significantly better than the old one overall, enough to justify the 
hassle of switching.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Óscar Fuentes <ofv@wanadoo.es>,
>     emacs-devel@gnu.org
> Date: Fri, 12 Dec 2014 10:05:39 +0900
> 
> Eli Zaretskii writes:
> 
>  > > 2. checking the resulting document in terms of appearance criteria can
>  > >    be done by another individual.
> 
>  > I also have hard time to imagine we will find volunteers for 2: it's a
>  > mundane, boring job that no one is motivated to do except the author.
> 
> Wiki has solved that problem.

Theoretically.  In practice, many wikis are in terrible disarray.

My evidence is the very small number (close to zero) of times we've
seen bug reports about typos and other clerical errors in Emacs
documentation.

Of course, one way to give more people motivation to do that is to
leave more errors in the docs.

Re: On being web-friendly and why info must die

[Ludovic Courtès]

Paul Eggert <eggert@cs.ucla.edu> skribis:

> Ludovic Courtès wrote:
>> if replacing Texinfo and/or Info results in loss of functionality
>> at all, that’s a showstopper.
>
> That's too strict.  We should not insist that the new documentation
> system must have every single feature that the old one does.  It
> should suffice if the new system is significantly better than the old
> one overall, enough to justify the hassle of switching.

Perhaps, but some features such as cross-manual references should be a
requirement, IMO.

(This discussion seems a bit surreal to me.  It sounds like: “our system
has all the features we need, but it’s ‘archaic’; so let’s drop a few
features so we can use something ‘modern’.”)

Ludo’.

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> ludo@gnu.org (Ludovic Courtès):

> (This discussion seems a bit surreal to me.  It sounds like: “our
> system has all the features we need, but it’s ‘archaic’; so let’s drop
> a few features so we can use something ‘modern’.”)

The speed complaints about Texinfo 5 makeinfo are real, though (this is
a place where a replacement must do significantly better....).

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Dec 11, 2014 at 6:20 PM, David Kastrup <dak@gnu.org> wrote:
>>
>> You were proposing to replace the Info search possibilities with a
>> search engine.  So it's up to you to explain what you mean.
>>
>> As for the index not disappearing: it's not accessible from arbitrary
>> nodes since it is not even loaded into the browser unless you load the
>> "one big page HTML" and then _all_ navigation becomes cumbersome,
>> including but not limited to the index.
>
> So that was the argument. OK. ;-)
>
> Yes, without a search engine you can't search the html pages. (Or, you
> could build an index in JavaScript, but that is a very tough job if
> you want to do something useful.)
>
> Of course you have to search the docs divided into several pages if a
> search engine should be of any use. Otherwise you will just get the
> same hit all the time. ;-)
>
> OpenSearchServer (based on Apache Lucene) is very flexible. Maybe you
> can't get exactly the incremental search that Info uses now, but you
> can get a list of suggestions for every character you type. You can
> customize that list.
>
> And Info does not have a search capability that is close to the usual
> web search (implicit) AND operator.
>
> But there is more you can use, like searching in fields (if the
> documents are structured with some fields, of course).

So the argument is that a huge flexible heap of complex technology
should make users just as happy as straightforward simple working
functionality.

Make no mistake: this kind of "it does not do what you want, but many
other potentially useful things" argument is very common in software
engineering.  It's sort of the sales point of Texinfo 5 according to the
criticism voiced against it here.  So the solution is to go Texinfo 5
squared?  I don't buy it.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Ludovic Courtès wrote:
>> if replacing Texinfo and/or Info results in loss of functionality
>> at all, that’s a showstopper.
>
> That's too strict.  We should not insist that the new documentation
> system must have every single feature that the old one does.  It
> should suffice if the new system is significantly better than the old
> one overall, enough to justify the hassle of switching.

So name a single respect in which any proposal is significantly better.
So far we had "it's new and hipper, so for the next two years it might
garner more fans".  What else?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eric S. Raymond]

David Kastrup <dak@gnu.org>:
> So name a single respect in which any proposal is significantly better.
> So far we had "it's new and hipper, so for the next two years it might
> garner more fans".  What else?

Increased visibility to search engines.  That's really important!
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: On being web-friendly and why info must die

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> David Kastrup <dak@gnu.org>:
>> So name a single respect in which any proposal is significantly better.
>> So far we had "it's new and hipper, so for the next two years it might
>> garner more fans".  What else?
>
> Increased visibility to search engines.  That's really important!

Red herring.  Texinfo-generated HTML is found just fine by search
engines.  I do it all the time for LilyPond's manuals.

Now LilyPond's manuals are nice and helpful with lots of images, and
people are referred to it a lot partly because of that.  So it has good
link coverage which makes search engines happy.

So it boils down to "make your manuals good and helpful so that people
refer to it a lot".  The temporary hipness of the source language does
not really play into that a lot.

If we add a command to the Info reader that will crank out the
corresponding web page for locally installed Info documentation so that
it can easily be cut and pasted into a reply on a public mailing list
for reference, this will do a lot more for increased page rank to search
engines (if they are GNU _manuals_ linked to on the project pages, they
are of course _visible_ to search engine crawlers) than messing with its
source language.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Phillip Lord]

Lennart Borgman <lennart.borgman@gmail.com> writes:
>> As for the index not disappearing: it's not accessible from arbitrary
>> nodes since it is not even loaded into the browser unless you load the
>> "one big page HTML" and then _all_ navigation becomes cumbersome,
>> including but not limited to the index.
>
> So that was the argument. OK. ;-)
>
> Yes, without a search engine you can't search the html pages. (Or, you
> could build an index in JavaScript, but that is a very tough job if
> you want to do something useful.)

I don't think it is a tough job. If the index data is in the source
format, and can be dumped in XML, then the JavaScript (or the lisp with
which to pimp up EWW) is really very simple.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Ludovic Courtès <ludo@gnu.org> writes:
>> Asiidoc does do indexes, as does docbook. And, yes, multiple output
>> formats. Seriously, almost everything does multiple output formats.
>
> OK.  What about documentation-oriented markup (think @deffn, @deftp) and
> cross-manual references?  They don’t do that, do they?

No. Asciidoc has a plugin mechanism (which I haven't used and can't
vouch for), so it could be extended. Org-mode texinfo export may have
this support, but I don't know. Both, of course, can do "pass-through",
and drop code straight to the output format.

Org-mode can pop out lisp and run it. Or it can eval code and put that
into the output format. How does this work in texinfo?

I've always wondered, with the emacs doc about things like this...

 -- Function: current-buffer
     This function returns the current buffer.

          (current-buffer)
               ⇒ #<buffer buffers.texi>


Now, this describes `current-buffer'. But the real documentation for
this is here:

doc: /* Return the current buffer as a Lisp object.  */

How do you include docstring from a lisp function or var in texinfo?


>> Web pages and browsers can do anything at all. Here is a webpage which boots
>> so linux and runs some of GNU
>
> I’ve heard of JavaScript, thank you ;-), but I’d rather (1) run code
> that’s hosted locally, and (2) be able to use a JS-less browser if I
> have to use a browser at all (I think it’s fair to assume that some
> Emacs users would rather use emacs-w3m or eww.)

Well, maybe once Emacs uses guile, we can run JS in eww. But in the same
way that a webpage can do anything at all, a web browser written for
Emacs can do anything at all, cause we can add lisp.


> Leaving out cross-manual refs would be a big loss for GNU as a project
> to develop a coherent system, because manuals would be left isolated.


Go to the Emacs manual, and type "i", and "current-buffer". [No match].
Which is strange, because there is documentation for current-buffer, in
the elips manual.

So, the manuals already are isolated. The info index functionality is
not really as rich as it seems.


> To me, if replacing Texinfo and/or Info results in loss of functionality
> at all, that’s a showstopper.  I’m surprised alternative systems are not
> studied with that in mind.

I have this great idea for a hypertext system. What it will do is have
globally unique identifiers, so that it is possible to put
cross-references between any two documents published using this
hypertext system. I shall the cross references IRIs (for Info Resource
Identifiers), and the whole system will be WWI (World-Wide Info). Are
you with me?

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Ludovic Courtès <ludo@gnu.org> writes:

> Paul Eggert <eggert@cs.ucla.edu> skribis:
>
>> Ludovic Courtès wrote:
>>> if replacing Texinfo and/or Info results in loss of functionality
>>> at all, that’s a showstopper.
>>
>> That's too strict.  We should not insist that the new documentation
>> system must have every single feature that the old one does.  It
>> should suffice if the new system is significantly better than the old
>> one overall, enough to justify the hassle of switching.
>
> Perhaps, but some features such as cross-manual references should be a
> requirement, IMO.
>
> (This discussion seems a bit surreal to me.  It sounds like: “our system
> has all the features we need, but it’s ‘archaic’; so let’s drop a few
> features so we can use something ‘modern’.”)


It has all the features that are currently used, I would say.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > John Kitchin wrote a GFDL licensed book on Density Functional Theory (a
>   > computationally efficient way of computing many quantum mechanical
>   > properties of materials) in Org mode.
>
> I am glad he did, but in order for Org format to be a usable format
> for GNU documentation, it needs to be fully documented.  To be good
> for the purpose, this documentation should not be dispersed among
> other unrelated topics such as outlines, memos, or time logging.

Org-mode does all of that, but doesn't have to do any of that. The
org-mode manual link which Achim Gratz is worth looking at.

Also, it's worth noting that texinfo current disperses the documentation
amount unrelated topics such as navigation.

Phil

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Paul Eggert <eggert@cs.ucla.edu> skribis:
>>
>>> Ludovic Courtès wrote:
>>>> if replacing Texinfo and/or Info results in loss of functionality
>>>> at all, that’s a showstopper.
>>>
>>> That's too strict.  We should not insist that the new documentation
>>> system must have every single feature that the old one does.  It
>>> should suffice if the new system is significantly better than the old
>>> one overall, enough to justify the hassle of switching.
>>
>> Perhaps, but some features such as cross-manual references should be a
>> requirement, IMO.
>>
>> (This discussion seems a bit surreal to me.  It sounds like: “our system
>> has all the features we need, but it’s ‘archaic’; so let’s drop a few
>> features so we can use something ‘modern’.”)
>
> It has all the features that are currently used, I would say.

Under torture?  I mean why else would you be saying that?

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Lennart Borgman]

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

On Dec 12, 2014 11:57 AM, "Phillip Lord" <phillip.lord@newcastle.ac.uk>
wrote:
>
> Lennart Borgman <lennart.borgman@gmail.com> writes:
> >> As for the index not disappearing: it's not accessible from arbitrary
> >> nodes since it is not even loaded into the browser unless you load the
> >> "one big page HTML" and then _all_ navigation becomes cumbersome,
> >> including but not limited to the index.
> >
> > So that was the argument. OK. ;-)
> >
> > Yes, without a search engine you can't search the html pages. (Or, you
> > could build an index in JavaScript, but that is a very tough job if
> > you want to do something useful.)
>
> I don't think it is a tough job. If the index data is in the source
> format, and can be dumped in XML, then the JavaScript (or the lisp with
> which to pimp up EWW) is really very simple.
>
> Phil

You may be right. It depends on what you want to do. Perhaps you have some
code to clarify what you mean?

[-- Attachment #2: Type: text/html, Size: 1289 bytes --]

Re: On being web-friendly and why info must die

[Lennart Borgman]

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

On Dec 12, 2014 10:57 AM, "David Kastrup" <dak@gnu.org> wrote:
>

> > OpenSearchServer (based on Apache Lucene) is very flexible. Maybe you
> > can't get exactly the incremental search that Info uses now, but you
> > can get a list of suggestions for every character you type. You can
> > customize that list.
> >
> > And Info does not have a search capability that is close to the usual
> > web search (implicit) AND operator.
> >
> > But there is more you can use, like searching in fields (if the
> > documents are structured with some fields, of course).
>
> So the argument is that a huge flexible heap of complex technology
> should make users just as happy as straightforward simple working
> functionality.

No. The point is to try to give new users something they are familiar with.

It must of course also be good.

If you do that you may save their time.

[-- Attachment #2: Type: text/html, Size: 1137 bytes --]

Re: On being web-friendly and why info must die

[martin rudalics]

 > How do you include docstring from a lisp function or var in texinfo?

Try `elinfo-get-definition' from elinfo.el.

http://lists.gnu.org/archive/html/bug-gnu-emacs/2009-08/msg00128.html

If it doesn't work I can send you my current version.

martin

Re: On being web-friendly and why info must die

[Phillip Lord]

Lennart Borgman <lennart.borgman@gmail.com> writes:
>> I don't think it is a tough job. If the index data is in the source
>> format, and can be dumped in XML, then the JavaScript (or the lisp with
>> which to pimp up EWW) is really very simple.
>>
>> Phil
>
> You may be right. It depends on what you want to do. Perhaps you have some
> code to clarify what you mean?

So, consider slidy:

http://www.w3.org/Talks/Tools/Slidy2/#%281%29

This implements next and previous buttons like info. At the bottom, you
should see a "contents?" button which gives you a table of contents. The
table of contents that you see is implemented in about 50 lines of
Javascript (including action handlers which always take up lots of
space). In this case the TOC is generated from the H1 tags in the
underlying HTML.

An index is, essentially, similar to a table of contents although more
complex. Index items could be added to an HTML presentation either as
div tags, which could be parsed for as slidy uses H1. Or, alternatively,
they could be placed in a XML file (index item to anchor) which would
save parsing the entire HTML file. On top of that, I would add a GUI --
so "i" would pop up an index with type ahead, so you could see what you
are searching through; there are, of course, quite a few type ahead
libraries available for HTML.

Of course, you might want to do more complex things; an "other pages
that point here" might be useful to give bidirectional links. A
set of categories pages to give richer context. A hover over tooltip
giving glossary information (might be quite useful given that many
users will misunderstand what the word "window" means in emacs space).

But at heart, I don't see indexes as a show stopper. It's probably
something that could have been added to texinfo HTML output years ago.

Note that when I say "javascript" where, the all the same things would
be possible in lisp. It has quite a few type ahead completion libraries
too, I believe...

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

martin rudalics <rudalics@gmx.at> writes:

>> How do you include docstring from a lisp function or var in texinfo?
>
> Try `elinfo-get-definition' from elinfo.el.
>
> http://lists.gnu.org/archive/html/bug-gnu-emacs/2009-08/msg00128.html
>
> If it doesn't work I can send you my current version.


I meant as a pointer. So

    @defdocstring{current-buffer}

would appear as 

    Return the current buffer as a Lisp object.

In the output format.

Phil

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Dec 12, 2014 10:57 AM, "David Kastrup" <dak@gnu.org> wrote:
>>
>
>> > OpenSearchServer (based on Apache Lucene) is very flexible. Maybe you
>> > can't get exactly the incremental search that Info uses now, but you
>> > can get a list of suggestions for every character you type. You can
>> > customize that list.
>> >
>> > And Info does not have a search capability that is close to the usual
>> > web search (implicit) AND operator.
>> >
>> > But there is more you can use, like searching in fields (if the
>> > documents are structured with some fields, of course).
>>
>> So the argument is that a huge flexible heap of complex technology
>> should make users just as happy as straightforward simple working
>> functionality.
>
> No. The point is to try to give new users something they are familiar
> with.

At the cost of giving old users something that is less useful to a
degree that isn't funny.  Because what new users are "familiar with" is
a crutch created to substitute for the case where nobody bothered
_either_ preparing a useful index, _or_ a useful keyboard interface to
it.

> It must of course also be good.

Either it is something new users are familiar with or it is good even in
relation to existing Info mode.  You can't have both.

Which is sort of sad seeing how old Info mode is.  Obviously
automatically prepared indices have a hard time competing with humans
(and indeed the major search engines _do_ put humans in the loop).  But
that's not really all that much of an excuse for browsers/HTML not
offering useful keyboard interfaces and mechanisms into searching and
indexing.

-- 
David Kastrup

Correspondence between web-pages and Info-pages

[Stefan Monnier]

> If we add a command to the Info reader that will crank out the
> corresponding web page for locally installed Info documentation so that
> it can easily be cut and pasted into a reply on a public mailing list
> for reference, this will do a lot more for increased page rank to search
> engines (if they are GNU _manuals_ linked to on the project pages, they
> are of course _visible_ to search engine crawlers) than messing with its
> source language.

Hey, I think this is a great idea: replace the "(emacs)Title"
syntax with a URL.  When passed to Info, these URL would be redirected
to the local Info pages.

The main downside is that those URLs would take up more space.  But the
upside is not just greater exposure of our HTML manuals to search
engines, but also the removal of the ad-hoc (info "(emacs)Title") syntax.


        Stefan

Re: On being web-friendly and why info must die

[martin rudalics]

 > I meant as a pointer. So
 >
 >      @defdocstring{current-buffer}
 >
 > would appear as
 >
 >      Return the current buffer as a Lisp object.
 >
 > In the output format.

What is a "pointer" and what is an "output format"?

martin

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Fri, Dec 12, 2014 at 2:36 PM, Phillip Lord
<phillip.lord@newcastle.ac.uk> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>>> I don't think it is a tough job. If the index data is in the source
>>> format, and can be dumped in XML, then the JavaScript (or the lisp with
>>> which to pimp up EWW) is really very simple.
>>>
>>> Phil
>>
>> You may be right. It depends on what you want to do. Perhaps you have some
>> code to clarify what you mean?
>
> So, consider slidy:
>
> http://www.w3.org/Talks/Tools/Slidy2/#%281%29
>
> This implements next and previous buttons like info. At the bottom, you
> should see a "contents?" button which gives you a table of contents. The
> table of contents that you see is implemented in about 50 lines of
> Javascript (including action handlers which always take up lots of
> space). In this case the TOC is generated from the H1 tags in the
> underlying HTML.
>
> An index is, essentially, similar to a table of contents although more
> complex. Index items could be added to an HTML presentation either as
> div tags, which could be parsed for as slidy uses H1. Or, alternatively,
> they could be placed in a XML file (index item to anchor) which would
> save parsing the entire HTML file. On top of that, I would add a GUI --
> so "i" would pop up an index with type ahead, so you could see what you
> are searching through; there are, of course, quite a few type ahead
> libraries available for HTML.
>
> Of course, you might want to do more complex things; an "other pages
> that point here" might be useful to give bidirectional links. A
> set of categories pages to give richer context. A hover over tooltip
> giving glossary information (might be quite useful given that many
> users will misunderstand what the word "window" means in emacs space).
>
> But at heart, I don't see indexes as a show stopper. It's probably
> something that could have been added to texinfo HTML output years ago.
>
> Note that when I say "javascript" where, the all the same things would
> be possible in lisp. It has quite a few type ahead completion libraries
> too, I believe...
>
> Phil

Thanks Phil, I see what you mean now.

I was thinking of more complex queries. Say you start with one word,
"word1". You get too many alternatives so you add "word2" to the
search string (or the search completion string). Perhaps you also have
fields you want to specify to narrow the search.

I guess that searching like that is what people are used to today
(except for fields, of course). I like the Emacs built in
documentation for functions and variables very much. However that is
limited to elisp. To me Info is much more inconvenient. Personally I
would prefer some searching enhanced with fields there.

Re: Correspondence between web-pages and Info-pages

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> If we add a command to the Info reader that will crank out the
>> corresponding web page for locally installed Info documentation so that
>> it can easily be cut and pasted into a reply on a public mailing list
>> for reference, this will do a lot more for increased page rank to search
>> engines (if they are GNU _manuals_ linked to on the project pages, they
>> are of course _visible_ to search engine crawlers) than messing with its
>> source language.
>
> Hey, I think this is a great idea: replace the "(emacs)Title"
> syntax with a URL.  When passed to Info, these URL would be redirected
> to the local Info pages.
>
> The main downside is that those URLs would take up more space.  But the
> upside is not just greater exposure of our HTML manuals to search
> engines, but also the removal of the ad-hoc (info "(emacs)Title") syntax.

Both Emacs browse-url as well as gnome-open will accept something like

Well, Emacs browse-url will accept

info:elisp#Strings%20and%20Characters

while gnome-open will accept

info:elisp#Strings_and_Characters

So, uh, we already have working URIs into the Info documentation.  For
some value of "working" and "uh".

But that's not what we are talking about here.  We are talking about
converting those into Internet HTML links rather than local Info or HTML
links (which are not all that useful for handing out).

It might also be worthwhile thinking about Internet Info links but
currently our Info browsers are not likely prepared for those.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[David Kastrup]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> I guess that searching like that is what people are used to today
> (except for fields, of course). I like the Emacs built in
> documentation for functions and variables very much. However that is
> limited to elisp. To me Info is much more inconvenient. Personally I
> would prefer some searching enhanced with fields there.

Shrug.  The Info index uses exactly the same completion/input as the
builtin documentation for functions and variables: wildcards, completion
lists and all.  Which is not much of a surprise since it uses the same
code.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Fri, 12 Dec 2014 11:19:24 +0000
> Cc: esr@thyrsus.com, emacs-devel@gnu.org
> 
> I've always wondered, with the emacs doc about things like this...
> 
>  -- Function: current-buffer
>      This function returns the current buffer.
> 
>           (current-buffer)
>                ⇒ #<buffer buffers.texi>
> 
> 
> Now, this describes `current-buffer'. But the real documentation for
> this is here:
> 
> doc: /* Return the current buffer as a Lisp object.  */

There are 2 (sometimes more) "real documentations" for each Emacs
symbol.  You somehow assume there should be just one, but that's a
false assumption.

The documentation is worded differently in the manual and in the doc
string because it targets 2 different use cases: the latter is for
immediate references while using Emacs, the former is for learning
about Emacs.  Therefore, the manual can have longer and more detailed
descriptions, while the doc string needs to be concise and cut to the
cheese very quickly.

> How do you include docstring from a lisp function or var in texinfo?

What for?

> Go to the Emacs manual, and type "i", and "current-buffer". [No match].
> Which is strange, because there is documentation for current-buffer, in
> the elips manual.
> 
> So, the manuals already are isolated. The info index functionality is
> not really as rich as it seems.

Your conclusion is wrong.  We describe each symbol in the manual(s)
where they are relevant.  The variable current-buffer is not relevant
to Emacs users, unless they write Lisp code, in which case they should
look in the ELisp manual.

There's also a Help command to find the documentation no matter which
manual it is in: "C-h S".  This command allows to find the manual, any
manual, where some symbol is defined, and it in a way makes all the
manuals a single searchable database.  You can try it with
current-buffer, if you like.

There are also "C-h F" and "C-h K".  No similar command for variables
exists, but it could be added if deemed important.

Re: On being web-friendly and why info must die

[Phillip Lord]

Lennart Borgman <lennart.borgman@gmail.com> writes:
>>> You may be right. It depends on what you want to do. Perhaps you have some
>>> code to clarify what you mean?
>>
>> So, consider slidy:
>>
>> http://www.w3.org/Talks/Tools/Slidy2/#%281%29
>>
>> This implements next and previous buttons like info. At the bottom, you
>> should see a "contents?" button which gives you a table of contents. The
>> table of contents that you see is implemented in about 50 lines of
>> Javascript (including action handlers which always take up lots of
>> space). In this case the TOC is generated from the H1 tags in the
>> underlying HTML.
>>
>> An index is, essentially, similar to a table of contents although more
>> complex. Index items could be added to an HTML presentation either as
>> div tags, which could be parsed for as slidy uses H1. Or, alternatively,
>> they could be placed in a XML file (index item to anchor) which would
>> save parsing the entire HTML file. On top of that, I would add a GUI --
>> so "i" would pop up an index with type ahead, so you could see what you
>> are searching through; there are, of course, quite a few type ahead
>> libraries available for HTML.
>>
>> Of course, you might want to do more complex things; an "other pages
>> that point here" might be useful to give bidirectional links. A
>> set of categories pages to give richer context. A hover over tooltip
>> giving glossary information (might be quite useful given that many
>> users will misunderstand what the word "window" means in emacs space).
>>
>> But at heart, I don't see indexes as a show stopper. It's probably
>> something that could have been added to texinfo HTML output years ago.
>>
>> Note that when I say "javascript" where, the all the same things would
>> be possible in lisp. It has quite a few type ahead completion libraries
>> too, I believe...
>>
>> Phil
>
> Thanks Phil, I see what you mean now.
>
> I was thinking of more complex queries. Say you start with one word,
> "word1". You get too many alternatives so you add "word2" to the
> search string (or the search completion string). Perhaps you also have
> fields you want to specify to narrow the search.
>
> I guess that searching like that is what people are used to today
> (except for fields, of course). I like the Emacs built in
> documentation for functions and variables very much. However that is
> limited to elisp. To me Info is much more inconvenient. Personally I
> would prefer some searching enhanced with fields there.


I would agree with this. I am, of course, glad that Emacs doc has an
index, but in general, indexes are disappearing from documentation,
because it's just as easy to search and less effort for the authors.
Also, of course, you can search outside the existing resource. This was
Eric's original motivation for moving from texinfo.

With the index as is, though, type ahead allows narrowing (buffer to
buffer,creating). 

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

martin rudalics <rudalics@gmx.at> writes:

>> I meant as a pointer. So
>>
>>      @defdocstring{current-buffer}
>>
>> would appear as
>>
>>      Return the current buffer as a Lisp object.
>>
>> In the output format.
>
> What is a "pointer" and what is an "output format"?


I don't want to put the docstring in. I want to put a reference to the
docstring. Then when I generate the PDF, html or Info, I want the
reference resolved.

My point is that org could do this with ease if we wanted it too.
Texinfo does not I suspect.

In the same way that I don't want to write

(current-buffer)
 => #<buffer *unsent wide reply to martin rudalics*>


I want to write "(current-buffer)" and have it evaled when the doc is
produced. This is the sort of thing that I expect when writing notes to
teach programming. Why would I not want it in Emacs?

I mention all of this because we have had lots of comments on things
that org cannot do. But texinfo is limited in other ways.

Phil

Re: On being web-friendly and why info must die

[David Kastrup]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> I would agree with this. I am, of course, glad that Emacs doc has an
> index, but in general, indexes are disappearing from documentation,
> because it's just as easy to search and less effort for the authors.

Just as easy to search?  No.  Less effort for the authors?  Yes.  Search
becomes fabulously useless where command names are built from common
words or get frequently referenced elsewhere.  Finding the actual
definition without the help of a manually prepared or polished index is
unrealistic.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Fri, 12 Dec 2014 14:46:33 +0000
> Cc: David Kastrup <dak@gnu.org>, Emacs-Devel devel <emacs-devel@gnu.org>
> 
> I would agree with this. I am, of course, glad that Emacs doc has an
> index, but in general, indexes are disappearing from documentation,

Yes, and people also read the documentation less and less, so what?
Are you arguing that we target those?

> because it's just as easy to search and less effort for the authors.

That's profoundly not true.  Many, if not most, of the index entries,
certainly those in the Concept Index, cannot be found anywhere in the
text.  They are concepts and phrases that the reader could have in
mind when she searches for some specific material without knowing its
exact wording.

There's no way you can search for that.

And, of course, you cannot easily search the printed manual.  But
that's secondary.

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Fri, 12 Dec 2014 14:50:00 +0000
> Cc: esr@thyrsus.com, Ludovic Courtès <ludo@gnu.org>,
> 	emacs-devel@gnu.org
> 
> I don't want to put the docstring in. I want to put a reference to the
> docstring.

What for?  What problem would that solve?

> I want to write "(current-buffer)" and have it evaled when the doc is
> produced. This is the sort of thing that I expect when writing notes to
> teach programming. Why would I not want it in Emacs?

First, you _can_ do that in Emacs.  We have infrastructure and
functions that return the doc strings.

But for writing a manual, this is usually not the right thing to do.
When you write a manual, you need to think differently than when you
write a doc string, otherwise there will be little added value in the
manual.

Yes, I know about projects that generate Texinfo sources of their
manuals from the doc strings.  But I consider those manuals of a lower
quality than what we have in Emacs.

RE: On being web-friendly and why info must die

[Drew Adams]

> I was thinking of more complex queries. Say you start with one word,
> "word1". You get too many alternatives so you add "word2" to the
> search string (or the search completion string). Perhaps you also
> have fields you want to specify to narrow the search.
> 
> I guess that searching like that is what people are used to today
> (except for fields, of course). 

That kind of searching is available in Emacs with packages such as
Icicles (I'm guessing there are others, perhaps Helm, but I can't
speak for others).

You can provide as many search patterns as you like.  And search is
incremental.  And patterns can themselves be complex (e.g. regexps).
And you can exclude pattern-matches as well.  And you can match node
names at the same time (again, using any number of patterns).

But yes, this is an area that could stand for some improvement in
Emacs.

Re: On being web-friendly and why info must die

[David Engster]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
> Richard Stallman <rms@gnu.org> writes:
>>   > John Kitchin wrote a GFDL licensed book on Density Functional Theory (a
>>   > computationally efficient way of computing many quantum mechanical
>>   > properties of materials) in Org mode.
>>
>> I am glad he did, but in order for Org format to be a usable format
>> for GNU documentation, it needs to be fully documented.  To be good
>> for the purpose, this documentation should not be dispersed among
>> other unrelated topics such as outlines, memos, or time logging.
>
> Org-mode does all of that, but doesn't have to do any of that. The
> org-mode manual link which Achim Gratz is worth looking at.

OK, I took a look. But more importantly, I actually *exported* that
thing to HTML. Apparently, all the people who are pitching Org as an
alternative to Texinfo have never actually tried that, because then they
would have witnessed this:

 > time emacs --batch -Q orgmanual.org --eval "(with-current-buffer \"orgmanual.org\" (org-export-to-file (quote html) \"orgmanual.html\"))"
 emacs --batch -Q orgmanual.org --eval   117.49s user 0.12s system 100% cpu 1:57.56 total

That's almost TWO MINUTES just for exporting one manual, and not even a
particularly big one. And that's on a Core i7.

For reference: For Org.texi, Texinfo5 needs ~8 seconds(!), and Texinfo4
needs ~0.7.

For me, Texinfo 5.2 is on average roughly 15 times slower than Texinfo 4
(for generating HTML). And people already say THAT is too slow. And Org
is about 167 times slower than Texinfo 4, at least for the Org manual (I
haven't looked, but I'd be willing to bet that this does not scale
linearly, so things are probably much worse for behemoths like the Calc
manual).

People were already saying around here that speed does not matter that
much for Org because you rarely export. I don't agree with that at all,
and I'm saying that as a heavy Org user. When writing stuff like
documentation or presentations in Org, I export *very* frequently, for
instance when I have to fit in pictures.

The whole Emacs docs are currently roughly 350k lines of Texinfo. The
Org manual is only 20k. So building the whole Emacs docs with Org would
easily take over 30 minutes on a Core i7. Yes, you can build in
parallel, so divide by four if you want, but that's still way too long,
and not everybody has that kind of machine (it's anybody's guess how
many hours this would take on RMS' MIPS-based laptop...).

I love Org. But people, please be reasonable about what it can and what
it cannot do. Unless someone makes the exporter *at least* an order of
magnitude faster, this is a non-starter.

-David

RE: Correspondence between web-pages and Info-pages

[Drew Adams]

> > If we add a command to the Info reader that will crank out the
> > corresponding web page for locally installed Info documentation so
> > that it can easily be cut and pasted into a reply on a public
> > mailing list for reference, this will do a lot more for increased
> > page rank to search engines (if they are GNU _manuals_ linked to
> > on the project pages, they are of course _visible_ to search
> > engine crawlers) than messing with its source language.
> 
> Hey, I think this is a great idea

http://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00627.html

> replace the "(emacs)Title" syntax with a URL.  When passed to Info,
> these URL would be redirected to the local Info pages.

The original suggestion (quoted in that reply by David K) was the
other way around: The web version of a manual uses URLs that are
derived from the Info manual.  Just keep that, but use that mapping
in Info to provide an Emacs command to retrieve the URL for a given
node (and so yank it or follow it etc.).

> The main downside is that those URLs would take up more space.  But
> the upside is not just greater exposure of our HTML manuals to search
> engines, but also the removal of the ad-hoc (info "(emacs)Title")
> syntax.

See above.  Provide the corresponding URL from Emacs, but continue
to use the current node refs within Info (Emacs).  No wasted space.
No downside.  FWIW, that "ad-hoc" node syntax is an Emacs feature,
not something that needs to be removed.

Either way (use a URL directly in Info/Emacs or provide a function
to get the URL for a given Info node), see the previous discussion
of this.

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Fri, Dec 12, 2014 at 3:44 PM, David Kastrup <dak@gnu.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>> I guess that searching like that is what people are used to today
>> (except for fields, of course). I like the Emacs built in
>> documentation for functions and variables very much. However that is
>> limited to elisp. To me Info is much more inconvenient. Personally I
>> would prefer some searching enhanced with fields there.
>
> Shrug.  The Info index uses exactly the same completion/input as the
> builtin documentation for functions and variables: wildcards, completion
> lists and all.  Which is not much of a surprise since it uses the same
> code.

Eh, yes. And that is both good and a problem. The logical structure of
the information you are looking for is perhaps a bit different.

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Fri, Dec 12, 2014 at 3:59 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> That's profoundly not true.  Many, if not most, of the index entries,
> certainly those in the Concept Index, cannot be found anywhere in the
> text.  They are concepts and phrases that the reader could have in
> mind when she searches for some specific material without knowing its
> exact wording.
>
> There's no way you can search for that.

The concept index is very good IMO. And is of course very useful when
you do a web search. Maybe even more so there.

Re: On being web-friendly and why info must die

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
>> Date: Fri, 12 Dec 2014 14:50:00 +0000
>> Cc: esr@thyrsus.com, Ludovic Courtès <ludo@gnu.org>,
>> 	emacs-devel@gnu.org
>> 
>> I don't want to put the docstring in. I want to put a reference to the
>> docstring.
>
> What for?  What problem would that solve?
>
>> I want to write "(current-buffer)" and have it evaled when the doc is
>> produced. This is the sort of thing that I expect when writing notes to
>> teach programming. Why would I not want it in Emacs?
>
> First, you _can_ do that in Emacs.  We have infrastructure and
> functions that return the doc strings.
>
> But for writing a manual, this is usually not the right thing to do.
> When you write a manual, you need to think differently than when you
> write a doc string, otherwise there will be little added value in the
> manual.
>
> Yes, I know about projects that generate Texinfo sources of their
> manuals from the doc strings.  But I consider those manuals of a lower
> quality than what we have in Emacs.

LilyPond does that in its reference appendices.  Of course, the
doc strings look Texinfoized in the source:

displayMusic =
#(define-music-function (parser location port music) ((output-port?) ly:music?)
   (_i "Display the internal representation of @var{music} to
@var{port}, default to the console.")
   (let ((port (or port (current-output-port))))
     (newline port)
     (display-scheme-music music port))
   music)

And are converted into
 @item @code{displayMusic} [music]  - @var{port} [output port] @var{music} (music)
@funindex displayMusic
Display the internal representation of @var{music} to
@var{port}, default to the console.

Basically, all LilyPond documentation strings are written in Texinfo.
Texinfo is lightweight enough not to make that annoying when you just
query the doc strings from Scheme.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Tom]

Lennart Borgman <lennart.borgman <at> gmail.com> writes:
> 
> Yes, without a search engine you can't search the html pages. (Or, you
> could build an index in JavaScript, but that is a very tough job if
> you want to do something useful.)
> 

With JS libraries, it's not that hard. As a test I created a simple
page to search the Emacs concept index. Just type in the textbox
something emacs related, the completions appear and if you select
one then it takes you to the relevant page of the emacs manual:

http://emacstest.byethost12.com/

The effective code which I wrote for this is about 4 lines
(aside from the index entries array, but I just generated that).

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> info:elisp#Strings%20and%20Characters

No, I meant an actual URL that will work "anywhere".  I.e. a link to the
online HTML docs, but which the Info reader would redirect to the local
(currently Info) pages.

I.e. something like

   http://www.gnu.org/software/emacs/manual/Control-Structures
or
   http://texinfo.org/emacs/Control-Structures

[ This latter one being probably preferable so non-GNU packages can
also have their place.  ]

Of course, we'd then have to make sure the www.gnu.org server serves the
right pages at those same places.  Obviously, Info uses the
"(manual)Title" syntax internally all over the place, so we won't want
to completely remove this syntax, but we should use the URL syntax
outside of Info-mode (e.g. in docstrings).


        Stefan

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Not by itself, but with a good search engine it could. I am just
  > testing http://www.opensearchserver.com/ and I am surprised by the
  > quality and the easy of use - even locally.

What sort of thing is that?  You referred to it with a URL; does that
mean it is a web service?  Or is it a program?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The problem is that GNU manuals refer to each other, and Texinfo nodes
  > are part of their public interface, in a way.

  > Leaving out cross-manual refs would be a big loss for GNU as a project
  > to develop a coherent system, because manuals would be left isolated.

Thanks for remembering this feature.
We certainly want inter-manual cross references.
Input formats need to be able to support them.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > * Introduction
  >   :PROPERTIES:
  >   :TITLE: Introduction
  >   :DESCRIPTION: Getting started
  >   :END:
  > {{{cindex(introduction)}}}

How would you format a title page as in the Emacs manual?
Is there an "escape to TeX" construct that could be used?

  > in queries and create dynamic /agenda views/.

Is there a way to distinguish between emphasis and definitional
occurrences and variable values?  In Texinfo, @emph and @dfn and @var.
They all appear as italic in printed manuals, but may be different
in other output formats.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Alternative input formats

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > But HTML itself lacks the notion of indexes or cross-manual references,
  > for instance (cross-manual references must work both with on-line copies
  > and with locally installed manuals.)

It is true that these concepts as such do not appear in the specs
of HTML.  But there are ways to deal with that.
For instance, we could define a particular structure of HTML code
to represent the index of a manual.

As for cross-manual references, can't we represent them
as links?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > But is not "enemy" a bad word too? I think you use it to say those
  > people believe in other things.

No, I am talking about proprietary software developers, purveyors of
DRM, and such.  They want power over people, and we fight to take
away their power.

"Enemies" is exactly the word for that.

  > Using the word "enemy" might make it more difficult to listen to them.
  > Good ideas comes also from people we do not always agree with.

We have no prejudice against good TECHNICAL ideas that happen to come
from our enemies.  But this is not a technical competition.  We are
fighting to give users freedom, and our enemies are fighting to deny
users that same freedom.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[martin rudalics]

 > I don't want to put the docstring in. I want to put a reference to the
 > docstring. Then when I generate the PDF, html or Info, I want the
 > reference resolved.

Lazily?  Why?  Do you assume the docstring could change in between writing
the documentation and producing the Info file?

 > In the same way that I don't want to write
 >
 > (current-buffer)
 >   => #<buffer *unsent wide reply to martin rudalics*>
 >
 >
 > I want to write "(current-buffer)" and have it evaled when the doc is
 > produced. This is the sort of thing that I expect when writing notes to
 > teach programming. Why would I not want it in Emacs?

I can understand that this might be useful for a tutorial.  But in a
documentation?

martin

Re: On being web-friendly and why info must die

[Lennart Borgman]

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

Yes, the libraries for those kind of things are good. :-)
On Dec 12, 2014 5:24 PM, "Tom" <adatgyujto@gmail.com> wrote:

> Lennart Borgman <lennart.borgman <at> gmail.com> writes:
> >
> > Yes, without a search engine you can't search the html pages. (Or, you
> > could build an index in JavaScript, but that is a very tough job if
> > you want to do something useful.)
> >
>
> With JS libraries, it's not that hard. As a test I created a simple
> page to search the Emacs concept index. Just type in the textbox
> something emacs related, the completions appear and if you select
> one then it takes you to the relevant page of the emacs manual:
>
> http://emacstest.byethost12.com/
>
> The effective code which I wrote for this is about 4 lines
> (aside from the index entries array, but I just generated that).
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 1271 bytes --]

Re: On being web-friendly and why info must die

[Achim Gratz]

David Engster writes:
>  > time emacs --batch -Q orgmanual.org --eval "(with-current-buffer \"orgmanual.org\" (org-export-to-file (quote html) \"orgmanual.html\"))"
>  emacs --batch -Q orgmanual.org --eval   117.49s user 0.12s system 100% cpu 1:57.56 total
>
> That's almost TWO MINUTES just for exporting one manual, and not even a
> particularly big one. And that's on a Core i7.

Told you so.  But the discussion at the moment is whether Org would be a
suitable format, not whether the export is slow.

> For me, Texinfo 5.2 is on average roughly 15 times slower than Texinfo 4
> (for generating HTML). And people already say THAT is too slow. And Org
> is about 167 times slower than Texinfo 4, at least for the Org manual (I
> haven't looked, but I'd be willing to bet that this does not scale
> linearly, so things are probably much worse for behemoths like the Calc
> manual).

I've looked at the complexity together with Nicolas and yes it is known
to be at least quadratic in the number of (sub-)sections.  Some of that
could be avoided, but at the moment the focus in developing the
org-element code is on correctness.  The Cals manual is roughly twice as
big (in bytes), I haven't looked at the sectioning, though.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf rackAttack:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
> How would you format a title page as in the Emacs manual?

I've left out the preamble of the manual that defines the title, among
other things.  In general I'd thing Org would need to have a derived
export backend for the kind of manuals you are thingkning about that
took care about these things.

> Is there an "escape to TeX" construct that could be used?

Yes, although you wouldn't want to use it in this case.  You'd have to
replicate its effect for all export targets you intend to use.

>   > in queries and create dynamic /agenda views/.
>
> Is there a way to distinguish between emphasis and definitional
> occurrences and variable values?  In Texinfo, @emph and @dfn and @var.
> They all appear as italic in printed manuals, but may be different
> in other output formats.

See, that's one thing no "unobtrusive" or "visual" markup can provide.
For Org, it seems that macros would be the way to go unless we'd come up
with yet another mechanism for semantic markup.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: On being web-friendly and why info must die

[David Engster]

Achim Gratz writes:
> David Engster writes:
>>  > time emacs --batch -Q orgmanual.org --eval "(with-current-buffer
>> \"orgmanual.org\" (org-export-to-file (quote html)
>> \"orgmanual.html\"))"
>>  emacs --batch -Q orgmanual.org --eval 117.49s user 0.12s system
>> 100% cpu 1:57.56 total
>>
>> That's almost TWO MINUTES just for exporting one manual, and not even a
>> particularly big one. And that's on a Core i7.
>
> Told you so.  But the discussion at the moment is whether Org would be
> a suitable format, not whether the export is slow.

No. This is not a theoretical discussion about formats. Whatever format
we might switch to must have an implementation that's suitable.

-David

Re: On being web-friendly and why info must die

[Ludovic Courtès]

phillip.lord@newcastle.ac.uk (Phillip Lord) skribis:

> Ludovic Courtès <ludo@gnu.org> writes:

[...]

>> Leaving out cross-manual refs would be a big loss for GNU as a project
>> to develop a coherent system, because manuals would be left isolated.
>
>
> Go to the Emacs manual, and type "i",

[...]

> So, the manuals already are isolated.

No, you’re talking about the index; I was referring to cross-manual
references.

Go to <http://www.gnu.org/software/guix/manual/guix.html> and notice
that one can seamlessly navigate to the manuals it refers to, such as
libc, Binutils, Emacs, Geiser, etc.

The same thing works when that manual is installed locally: the Info
browser automatically follows links to other locally-installed manuals.

>> To me, if replacing Texinfo and/or Info results in loss of functionality
>> at all, that’s a showstopper.  I’m surprised alternative systems are not
>> studied with that in mind.
>
> I have this great idea for a hypertext system. What it will do is have
> globally unique identifiers, so that it is possible to put
> cross-references between any two documents published using this
> hypertext system. I shall the cross references IRIs (for Info Resource
> Identifiers), and the whole system will be WWI (World-Wide Info). Are
> you with me?

No.  URLs are global: that’s what the HTML output of Texinfo uses; fine.

But I also want to be able to browse documentation installed on my
system, and that actually corresponds to software versions installed on
my system.  In that case, URLs fall short.  Instead, the documentation
browser needs to look up locally-installed manuals in some search path.

I hope this clarifies what I intended to convey.

Thanks,
Ludo’.

Re: On being web-friendly and why info must die

[Ludovic Courtès]

Richard Stallman <rms@gnu.org> skribis:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > The problem is that GNU manuals refer to each other, and Texinfo nodes
>   > are part of their public interface, in a way.
>
>   > Leaving out cross-manual refs would be a big loss for GNU as a project
>   > to develop a coherent system, because manuals would be left isolated.
>
> Thanks for remembering this feature.
> We certainly want inter-manual cross references.
> Input formats need to be able to support them.

Input *and* output formats.

HTML as an output format supports them for on-line manuals, provided the
manual-to-URL mapping can be configured as in Texinfo 5 (info "(texinfo)
HTML Xref Configuration"), but URLs don't work for locally-installed
manuals.

Ludo'.

Info replacement?

[Ludovic Courtès]

Richard Stallman <rms@gnu.org> skribis:

>   > But HTML itself lacks the notion of indexes or cross-manual references,
>   > for instance (cross-manual references must work both with on-line copies
>   > and with locally installed manuals.)
>
> It is true that these concepts as such do not appear in the specs
> of HTML.  But there are ways to deal with that.
> For instance, we could define a particular structure of HTML code
> to represent the index of a manual.

A similar hack would be needed for menus.

> As for cross-manual references, can't we represent them
> as links?

URLs are either absolute (which would prevent use of locally-installed
manuals), or relative (which would typically force manuals to be
installed in same directory.)

Conversely, the Info mechanism whereby manuals are looked up in a search
path should be preserved, IMO.


TTN proposed a new output format, IXIN, as a possible Info replacement
more than a year ago:

  http://gnuvola.org/software/ixin/

It seems forward-looking, takes into account the strengths and
shortcomings of Info; there’s a written spec and code to work with it.

What about considering this option when it comes to replacing Info?

Thanks,
Ludo’.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I am glad he did, but in order for Org format to be a usable format
  > > for GNU documentation, it needs to be fully documented.  To be good
  > > for the purpose, this documentation should not be dispersed among
  > > other unrelated topics such as outlines, memos, or time logging.

  > Org-mode does all of that, but doesn't have to do any of that. The
  > org-mode manual link which Achim Gratz is worth looking at.

With all due respect, I don't think you have addressed the issue
I raised.

I looked at that manual text, and it doesn't do the job needed
to use Org format as a documentation source.

  > Also, it's worth noting that texinfo current disperses the documentation
  > amount unrelated topics such as navigation.

I don't follow you here.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > It has all the features that are currently used, I would say.

  > Under torture?  I mean why else would you be saying that?

That is a harsh response, and doesn't help understand the issue.
Would you please state your point focusing more on the issue
without directing emotion at the persons?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > http://www.w3.org/Talks/Tools/Slidy2/#%281%29

  > This implements next and previous buttons like info.

Do you have to click on the buttons to use them?  If so, that is not as
convenient as the Info reader, with its n and p commands.

I don't think any general web browser could give the convenience of
Info.  The Info-style n and p commands (and others) don't belong in a
general web browser.

However, I expect that a special purpose HTML-Info reader
could give all the same convenience, operating on a stylized form of HTML.

That would be a step up from using Info format
because it would support a lot more kinds of contents and structure.
Another advantage: the files WOULD be browsable with a general web browser,
even though that would be less convenient than browsing them
with the special purpose HTML-Info reader.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I think the discussion is going in a bad direction: HTML that
depends on Javascript.

I think an HTML-based format could be a step up, but special software
to use it should be a package for local installatoin, NOT Javascript
code to be included in web pages.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Alexis]

David Kastrup writes:

> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>
>> I would agree with this. I am, of course, glad that Emacs doc has an
>> index, but in general, indexes are disappearing from documentation,
>> because it's just as easy to search and less effort for the authors.
>
> Just as easy to search?  No.  Less effort for the authors?  Yes.  Search
> becomes fabulously useless where command names are built from common
> words or get frequently referenced elsewhere.

+10. Finding information in the Emacs and Emacs Lisp manuals via the
index is a profoundly pleasant change from my typical
documentation experiences.

From Emacs, i open the Emacs Lisp Reference Manual /within Emacs/, press
'i', type 'buffer', press RET, and am immediately taken to chapter 26,
"Buffers".

Now contrast that with opening the ELRM in Iceweasel, as a single page,
and then using text search within that page. i use the KeySnail addon
:-), so i press C-s and type 'buffer'. The first match is the link to
chapter 19, "Minibuffers". The next match is in the summary description
of that chapter, "Using the minibuffer to read input." It's the /third/
match that's the link to the "Buffers" chapter.

The gains of manually-tweaked indexes over pure search might seem modest
in this instance, but i've had experiences of trying to search through
/long/ manpages for certain text using nothing but text matching, and
compared to the experience of using the indexes of Emacs documentation,
it's .... rather painful. For example, try accessing the documentation
for the '-vo' option in the manpage for mplayer(1) ....

So, no, i can't agree with the assertion that using search is
necessarily just as easy for end users as using a well-maintained index.


Alexis.

Re: On being web-friendly and why info must die

[Nic Ferrier]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> I think the discussion is going in a bad direction: HTML that
> depends on Javascript.
>
> I think an HTML-based format could be a step up, but special software
> to use it should be a package for local installatoin, NOT Javascript
> code to be included in web pages.

I did this a while ago:

  http://gnudoc.ferrier.me.uk

it's a sketch of an HTML/JS based viewer that works in the web browser.

I agree that a stand alone viewer should work but I'd like to think we
could construct something in such a way that made it possible to make a
web version AND a version for emacs AND a version to run on a computer
without a web browser or emacs.


At the time you were enthusiastic about my webapp. You encouraged me to
keep working on it. I have. I hope your view hasn't changed.



Nic


PS I am also working on an emacs-lisp -> javascript compiler so we could
write the javascript part of a webapp in emacs-lisp.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I've left out the preamble of the manual that defines the title, among
  > other things.  In general I'd thing Org would need to have a derived
  > export backend for the kind of manuals you are thingkning about that
  > took care about these things.

Documentation of how to write such things in Org format
is part of what is needed for Org format to be a candidate
for a GNU documentation format.

  > > Is there a way to distinguish between emphasis and definitional
  > > occurrences and variable values?  In Texinfo, @emph and @dfn and @var.
  > > They all appear as italic in printed manuals, but may be different
  > > in other output formats.

  > See, that's one thing no "unobtrusive" or "visual" markup can provide.

I do see that it is not straightforward -- but this feature is
something we need.

  > For Org, it seems that macros would be the way to go unless we'd come up
  > with yet another mechanism for semantic markup.

What would this look like?

A solution that occurs to me is to use character pair brackets, such
as _*foo*_ and _#foo#_ and *#foo#*.  These would provide enough
alternatives to make the necessary distinctions.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I meant as a pointer. So

  >     @defdocstring{current-buffer}

  > would appear as 

  >     Return the current buffer as a Lisp object.

  > In the output format.

There are two reasons we don't want to do this.

1. We want the manual text to be specified in the manual sources,
not referred to some other file.

2. The text that makes a good doc string is not good for the manual.

A feature to facilitate using the same text for both is inherently not
a good idea.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > HTML as an output format supports them for on-line manuals, provided the
  > manual-to-URL mapping can be configured as in Texinfo 5 (info "(texinfo)
  > HTML Xref Configuration"), but URLs don't work for locally-installed
  > manuals.

Can we define a new type of URL to refer to a locally-installed
HTML-Info manual?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Info replacement?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > TTN proposed a new output format, IXIN, as a possible Info replacement
  > more than a year ago:

  >   http://gnuvola.org/software/ixin/

  > It seems forward-looking, takes into account the strengths and
  > shortcomings of Info; there s a written spec and code to work with it.

  > What about considering this option when it comes to replacing Info?

Could someone who understands Info please review it thoroughly and
comment?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Ludovic Courtès]

Richard Stallman <rms@gnu.org> skribis:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > HTML as an output format supports them for on-line manuals, provided the
>   > manual-to-URL mapping can be configured as in Texinfo 5 (info "(texinfo)
>   > HTML Xref Configuration"), but URLs don't work for locally-installed
>   > manuals.
>
> Can we define a new type of URL to refer to a locally-installed
> HTML-Info manual?

That's a possibility (ISTR that KDE's browser supported info://), but
most browsers won't support it out of the box.

Ludo'.

Re: On being web-friendly and why info must die

[chad]

> On 12 Dec 2014, at 17:47, Richard Stallman <rms@gnu.org> wrote:
> 
>> http://www.w3.org/Talks/Tools/Slidy2/#%281%29
> 
>> This implements next and previous buttons like info.
> 
> Do you have to click on the buttons to use them?  If so, that is not as
> convenient as the Info reader, with its n and p commands.

No, the mouse is not required in any way. 

The package is designed to work like presentation programs, rather
than info, so its key-bindings are different, but theyre no less
functional. The second page of that presentation includes this text:

* Advance to next slide with mouse click, space bar or swipe left
* Move forward/backward between slides with Cursor Left, Cursor 
  Right, Pg Up and Pg Dn keys, or swipe left or right
* Home key for first slide, End key for last slide
* The "C" key for an automatically generated table of contents, or 
  click on "contents" on the toolbar or swipe up or down
* Function F11 to go full screen and back
* The "F" key toggles the display of the footer
* The "A" key toggles display of current vs all slides
* Switching off JavaScript reveals all slides

> I don't think any general web browser could give the convenience of
> Info.  The Info-style n and p commands (and others) don't belong in a
> general web browser.

Web browsers *that can run javascript* are far more capable (in
terms of available functionality) than info browsers other than
emacs, and have been for a while now. By way of example, someone
recently posted a link to a page that runs a PC emulator and boots
a unix kernel, using only the web browser's functionality. Making
a general web browser of the sort that is considered baseline
functionality these days do everything that the info browser needs
to do is not at all hard from a technical standpoint; the harder
part is getting the information that the program needs in a way
that is convenient (particularly in time and mental effort) the
documentation-writers want is a harder concern.

This sort of functionality uses client-side javascript, which is
something of a concern. That's a separate problem worth addressing,
but seems likely to be a distraction from the current topic. If
client-side javascript is a deal-breaker for this topic, I suggest
that you just declare it so and move on.

I hope that helps,
~Chad

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
> Documentation of how to write such things in Org format
> is part of what is needed for Org format to be a candidate
> for a GNU documentation format.

Yes, but turning the tables: what exactly are the requirements for a GNU
documentation format?  If it turns out to be "exactly like texinfo",
then any other contender would have to be leaps and bounds better in at
least one or two other respects to be even considered seriously.

>   > For Org, it seems that macros would be the way to go unless we'd come up
>   > with yet another mechanism for semantic markup.
>
> What would this look like?

The macro invocations are those things in triple curly braces in the
manual section I posted.

This would be a macro defintion for a macro taking no argument

#+MACRO: page @@info:@page@@

while these two take arguments and the latter is using a macro within
its own definition

#+MACRO: markup @@info:@$1{@@$2@@info:}@@
#+MACRO: kbd {{{markup(kbd,$1)}}}

These macros define output specific to the info export backend by using
a so-called export snippet.  You could write these directly, but doing
this via macro expansion reduces the tedium somewhat.

> A solution that occurs to me is to use character pair brackets, such
> as _*foo*_ and _#foo#_ and *#foo#*.  These would provide enough
> alternatives to make the necessary distinctions.

Defining new syntax for Org that doesn't collide with already existing
things is not easy.  In this particular case, I don't even see an
advantage since the pair brackets aren't in any way self-describing, so
one would have to look them up each time they need to be used.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf rackAttack:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Can we define a new type of URL to refer to a locally-installed
  > > HTML-Info manual?

  > That's a possibility (ISTR that KDE's browser supported info://), but
  > most browsers won't support it out of the box.

That is not an important obstacle.  This is still a solution.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > At the time you were enthusiastic about my webapp.

A few years ago I became aware of how "web apps", by running software
straight off someone else's web page, deny the user control over his
computing.  To make Javascript acceptable we need to give users a way
to develop and run modified versions of it.

Thus, the truly ethical way to put Javascript code into service is NOT
to send it from a server at all; rather, to package it for installation
locally just like C programs.

  > PS I am also working on an emacs-lisp -> javascript compiler so we could
  > write the javascript part of a webapp in emacs-lisp.

Which language the code is written in is an independent issue.
Javascript and Emacs Lisp are both ok source languages, but each
user must control what version of the source he actually uses.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Achim Gratz]

[This is getting off-topic for Emacs, so maybe suggest another venue to
 discuss it.]

Richard Stallman writes:
>   > At the time you were enthusiastic about my webapp.
>
> A few years ago I became aware of how "web apps", by running software
> straight off someone else's web page, deny the user control over his
> computing.  To make Javascript acceptable we need to give users a way
> to develop and run modified versions of it.

I don't think that Javascript (or rather ECMAScript) has anything to do
with that, except as a prominent example.  SaaS (software as a service)
is another one and there certainly are ways to deny the user control
over locally installed software.

> Thus, the truly ethical way to put Javascript code into service is NOT
> to send it from a server at all; rather, to package it for installation
> locally just like C programs.

I see that as a red herring mostly.  For most of the scripting in web
pages it wouldn't be difficult to extract the scripts and inject local
modifications.  Support for additional user scripting has been available
as an extension in some browsers (GreaseMonkey and others).  As another
example, NoScript (a Firefox extension) has so-called surrogates that
replace some tracking scripts with definitions that do nothing, but keep
the expected API intact.  I'm not aware of a general "snarf all scripts
and from then on use the local copy" functionality existing, however.
It would be possible to implement it using the same facilities that user
scripts or surrogates use, however.

The real issues are those parts of the data and application that then
still are not under the user's control and even where they are, the fact
that the owner of the service and other parties gets to see what the
user is doing.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf rackAttack V1.04R1:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> > Can we define a new type of URL to refer to a locally-installed
>> > HTML-Info manual?

I don't think that's interesting.  A more interesting URL is one that
works both as a reference to locally-installed manuals and as
a reference to some remote manual (when not available locally).


        Stefan

Re: On being web-friendly and why info must die

[Achim Gratz]

Stefan Monnier writes:
>>> > Can we define a new type of URL to refer to a locally-installed
>>> > HTML-Info manual?
>
> I don't think that's interesting.  A more interesting URL is one that
> works both as a reference to locally-installed manuals and as
> a reference to some remote manual (when not available locally).

The right solution is still an URI scheme for info documentation and a
resolver that prefers locally installed documentation over the canonical
and/or mirror sources on the network.  That implementation could
generally cache documents from the net or install such documentation
locally when requested by the user.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Terratec KOMPLEXER:
http://Synth.Stromeko.net/Downloads.html#KomplexerWaves

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

chad writes:

 > Web browsers *that can run javascript* are far more capable (in
 > terms of available functionality) than info browsers other than
 > emacs, and have been for a while now.

Only if the ecmascript has been written.

 > This sort of functionality uses client-side javascript, which is
 > something of a concern.

I don't see why that's more of a concern than "client-side Lisp".  The
problem with ecmascript on the web is (a) licensing and (b) whether
you can trust the source.  I would think that for Emacs's HTML manuals
the emacscript would of course be GPL, and distributed with the manuals.

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Richard Stallman writes:

 > Can we define a new type of URL to refer to a locally-installed
 > HTML-Info manual?

URLs are already sufficiently flexible.  You can run a dedicated HTTP
server for http: schemes or use a file: URL for local files.  To
reference sub-file objects you use the #fragment notation.

You'd only need a different scheme if you want URNs for info manuals
such that Emacs could check for one installed locally and then go out
to some canonical location on the web if not found.

Re: On being web-friendly and why info must die

[Yuri Khan]

On Sun, Dec 14, 2014 at 7:40 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

> I don't think that's interesting.  A more interesting URL is one that
> works both as a reference to locally-installed manuals and as
> a reference to some remote manual (when not available locally).

There is a precedent for that.

In XML processing, a schema or a DTD is typically identified by an
http:// URL. Fetching that URL typically gets you the relevant schema
or DTD. E.g. any XHTML 1.0 document contains a DTD declaration
referring to one of http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd,
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd or
http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd.

However, it is not really expected that applications that process such
documents actually fetch those URLs. Instead, they are treated as
well-known URLs, their content installed in a file on the local file
system and the URL-to-file correspondence registered in a system-wide
map called the XML Catalog.

It should be possible to adopt a convention that manuals can be
packaged, installed on the local system and registered in a
system-wide or user-specific catalogs, and build info browsers that,
given a node URL, first look up if the corresponding manual is
installed locally, and if not, fetch the content from the web.

Different versions of the manuals could be assigned different base
URLs. E.g. Python manuals start at
https://docs.python.org/<version>/library/ where <version> can be an
exact major.minor version number (2.6, 2.7, 3.2, 3.3, 3.4, 3.5) or a
major-only version (2, 3) pointing to the current stable release of
that major version.

The implicit idea is that local content is an identical cache copy of
the remote content. However it doesn’t have to be. Local content might
be in a different format or medium more suitable for local use, or
localized into a different language. The same mechanism could be used
to give the user a means to override remote client-side code with a
local version.

Re: On being web-friendly and why info must die

[chad]

> On 14 Dec 2014, at 06:25, Stephen J. Turnbull <stephen@xemacs.org> wrote:
> 
> Richard Stallman writes:
> 
>> Can we define a new type of URL to refer to a locally-installed
>> HTML-Info manual?
> 
> URLs are already sufficiently flexible.  You can run a dedicated HTTP
> server for http: schemes or use a file: URL for local files.  To
> reference sub-file objects you use the #fragment notation.
> 
> You'd only need a different scheme if you want URNs for info manuals
> such that Emacs could check for one installed locally and then go out
> to some canonical location on the web if not found.

Further, that is only interesting if you dont control the browser.
Specifically, a browser in emacs could look for http URLs with a
canonical form like ^http://www.gnu.org/manual/ and prefer locally
installed manuals instead. This means that someone using, say,
Firefox or MSIE to follow a manual link would use the remote manuals
(without specific local steps), but that seems ok, and doesnt require
the user to run local servers.

It might be that we decide we want something different eventually,
but this is something that can be written and used very quickly,
unlike getting a new URI.

~Chad

Re: On being web-friendly and why info must die

[chad]

> On 14 Dec 2014, at 06:20, Stephen J. Turnbull <stephen@xemacs.org> wrote:
> 
> chad writes:
> 
>> Web browsers *that can run javascript* are far more capable (in
>> terms of available functionality) than info browsers other than
>> emacs, and have been for a while now.
> 
> Only if the ecmascript has been written.

True, but weve already seen both interest in doing so and moderately
near misses in existing code posted to this thread.  This seems
like a fairly minor concern. More troublesome (at least to me) is
the fact that the closest we get to such a browser in emacs is
xwidget.

> 
>> This sort of functionality uses client-side javascript, which is
>> something of a concern.
> 
> I don't see why that's more of a concern than "client-side Lisp".  The
> problem with ecmascript on the web is (a) licensing and (b) whether
> you can trust the source.  I would think that for Emacs's HTML manuals
> the emacscript would of course be GPL, and distributed with the manuals.

I might be wrong, but I believe that Richard is generally unhappy
about software that the user runs without really being aware. It
would be interesting to see browsers and javascript packages adopt
a GPL-compatibility declaration, along the same lines as the approach
used in gcc or expected to be used in an Emacs FFI. There are
practical ways in which users can exert some control over client-side
javascript today (GreaseMonkey, NoScript, and the like).

The technical hurdles to creating a similar tool that looked for a
GPL-compliance declaration and displayed it along with an easy way
to get to (and maybe modify) the source code arent too high. The
harder part, I guess, is the political effort needed to get web
developers to use it. Theres a lot of library and framework use in
that world today, which suggests that efforts on a few key places
might provide good return.

~Chad

Re: On being web-friendly and why info must die

[Stefan Monnier]

> I don't see why that's more of a concern than "client-side Lisp".

Or any other language for that matter, indeed.

> The problem with ecmascript on the web is (a) licensing and (b)
> whether you can trust the source.

There's also the (c) which is that it's a lot more difficult to modify
this code.  There's the issue of performing the modification itself, but
also the fact that the code you run is often tightly integrated with
external code or with the specific format of the served document, so
even if you can arrange some kind of "on the fly rewrite or redirection"
the code, you may be served a completely different kind of code next
time around and the change you made may have become unusable.


        Stefan

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

chad writes:

 > True, but weve already seen both interest in doing so and moderately
 > near misses in existing code posted to this thread.  This seems
 > like a fairly minor concern.

Not really.  The question is practical: can such a system be as agile
as Info is?  I believe the answer is yes, except but browsers are
heavy beasts.  It may not work as well as we hope.

 > More troublesome (at least to me) is the fact that the closest we
 > get to such a browser in emacs is xwidget.

I don't see why that's relevant.  ISTM that people who advocate use of
HTML intend to use full-featured browsers like Firefox anyway, and
probably won't even bother to learn the hotkeys for Info-style
navigation.  Emacs can have its own documentation browser with a UI
based on Info mode.

 > I might be wrong, but I believe that Richard is generally unhappy
 > about software that the user runs without really being aware.

Surely not.  Running without your knowledge of the details is *what
software is for*.  Richard of all people is aware of that -- that's
why software freedom is so important, so you can exert control when
you choose.  Even most modern content formats are basically programs
with specialized interpreters (hello, PDF -- it's 10pm, do you know
what mischief is executing in your Postscript[tm] printer?)  Another
way to look at it: do you know the names of all the libraries that are
loaded in your Emacs?  (In my XEmacs I currently have a features
variable of length 442.  The first 100 or so are all library features.)

 > It would be interesting to see browsers and javascript packages
 > adopt a GPL-compatibility declaration,

Good luck.  The people advocating HTML are using IE, Firefox, Chrome,
or Safari (or DFSG variants of the above, where legally feasible), I'd
bet.  GPL browsers are minor.

 > There are practical ways in which users can exert some control over
 > client-side javascript today (GreaseMonkey, NoScript, and the like).

I think that's a much better approach.  I really don't care if the
code I'm running is GPL or another FLOSS license or public domain.
After all, the browsers I use most of the time aren't even GPL
themselves.  I don't think crackers and phishers will hesitate to
fraudulently present a GPL assertion, either.  So what I really want
is a feature that tells me that I haven't run this script before and
asks me if I want to run it.

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Stefan Monnier writes:

 > > The problem with ecmascript on the web is (a) licensing and (b)
 > > whether you can trust the source.
 > 
 > There's also the (c) which is that it's a lot more difficult to modify
 > this code.

That's not at all the same kind of problem.  If you don't like the
style of code, rewrite it.  If it interacts with proprietary resources
(whether by license or by hiding in the cloud), that's a problem with
the resources, not with the downloaded code.  "Difficult to modify" !=
unfree or fraudulent.  After all, that's what Eric and Karl are saying
about Emacs itself. ;-)

Re: On being web-friendly and why info must die

[David Engster]

Stephen J. Turnbull writes:
> Stefan Monnier writes:
>
>  > > The problem with ecmascript on the web is (a) licensing and (b)
>  > > whether you can trust the source.
>  > 
>  > There's also the (c) which is that it's a lot more difficult to modify
>  > this code.
>
> That's not at all the same kind of problem.  If you don't like the
> style of code, rewrite it.

Javascript code is usually "minimized" before it is put on the
server. This however has the side effect of also obfuscating the code
beyond recognition. Good luck rewriting that.

-David

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

If HTML-Info is implemented in Javascript, we could release it
as an extension for Firefox and IceCat that users can install.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Yes, but turning the tables: what exactly are the requirements for a GNU
  > documentation format?

It has to have all the features offered by Texinfo, except that if you
can show a certain Texinfo feature is hardly ever used by GNU manuals,
maybe it can be omitted.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The Org macros might do the job.  I am not sure, but I think that kbd
in Org format will look a lot like @kbd in Texinfo, but longer.  So it
seems that there is no advantage in Org format.

  > > A solution that occurs to me is to use character pair brackets, such
  > > as _*foo*_ and _#foo#_ and *#foo#*.  These would provide enough
  > > alternatives to make the necessary distinctions.

  > Defining new syntax for Org that doesn't collide with already existing
  > things is not easy.  In this particular case, I don't even see an
  > advantage since the pair brackets aren't in any way self-describing,

I think they can be self-describing, and they could be shorter and
less cumbersome than the current Texinfo syntax.

If you send me a list of the current simple markup characters,
I could make some proposals.

I agree that we should not go overboard on this.  It might be good for
10 common constructs to have character pairs to designate them, while
using Texinfo-like format with braces for the rest of the constructs.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I don't think that's interesting.  A more interesting URL is one that
  > works both as a reference to locally-installed manuals and as
  > a reference to some remote manual (when not available locally).

That would be ok too, I guess.  Either way, it would look the same
and could be used the same.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >  > This sort of functionality uses client-side javascript, which is
  >  > something of a concern.

  > I don't see why that's more of a concern than "client-side Lisp".

"Client-side Javascript" is a simple referrence to the problem,
but if you take it as a complete description of the problem, that
can lead to misunderstanding what the issue is.

The problem with Javascript is in the form of its usual usage
scenario: the browser gets it in a web page sent by some other machine
and runs it directly from that page.  That's the way "client-side
Javascript" usually works.

If someone takes a verbal shortcut and refers to that problem by
saying "client-side Javascript", would you please keep in mind that
the real issue is what I stated in the paragraph above?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >  > Can we define a new type of URL to refer to a locally-installed
  >  > HTML-Info manual?

  > URLs are already sufficiently flexible.  You can run a dedicated HTTP
  > server for http: schemes or use a file: URL for local files.  To
  > reference sub-file objects you use the #fragment notation.

We want to write something short such as `info:emacs' to refer to the
Emacs manual.  I don't think 'file:' does things like that.  As for
the local HTTP server, getting these results wiht it might be
complicated since it might be doing other jobs.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Richard Stallman writes:

 > If someone takes a verbal shortcut and refers to that problem by
 > saying "client-side Javascript", would you please keep in mind that
 > the real issue is what I stated in the paragraph above?

I understand the real issue.  The post I was responding to didn't seem
to, especially not in a context where we're discussing Emacs (or GNU)
development of an alternative documentation format.

I also object to the shortcut itself.  An accurate phrasing would be
"server-supplied Javascript", and I don't see why you would encourage
use of the rather inaccurate and misleading "client-side Javascript".

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Richard Stallman writes:

 > We want to write something short such as `info:emacs' to refer to the
 > Emacs manual.

Why?  I don't think either the browser maintainers or the IETF will be
particularly interested in an info: scheme since it's really a
document format rather than a transport.  If it's not widely
implemented, it will only be useful in the context of a specialized
InfoML-reading application.  In that case, just "emacs" is shorter.

 > As for the local HTTP server, getting these results wiht it might
 > be complicated since it might be doing other jobs.

I don't see why it would.  HTTP servers are cheap and easy to build,
and you can have a bunch of application-specific httpds running on any
modern system without any noticable resource impact.

Re: On being web-friendly and why info must die

[David Kastrup]

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

> Richard Stallman writes:
>
>  > We want to write something short such as `info:emacs' to refer to the
>  > Emacs manual.
>
> Why?  I don't think either the browser maintainers or the IETF will be
> particularly interested in an info: scheme since it's really a
> document format rather than a transport.

This discussion seems a bit surreal since

    gnome-open info:emacs

already opens a help browser on the Emacs documentation.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stefan Monnier]

> We want to write something short such as `info:emacs' to refer to the
> Emacs manual.

I don't.  Yes, I want it to be "as short as possible", but I also want
it to work when passed to any random web-browser.
So it pretty much has to look like "http://<hostname>/<somethingelse>".


        Stefan

Re: On being web-friendly and why info must die

[Ivan Andrus]

> On Dec 15, 2014, at 1:39 AM, Richard Stallman <rms@gnu.org> wrote:
> 
> If someone takes a verbal shortcut and refers to that problem by
> saying "client-side Javascript", would you please keep in mind that
> the real issue is what I stated in the paragraph above?

If you keep in mind that when I say Linux, I mean GNU/Linux.  :-)

IOW, words are important and IMHO you (i.e. the FSF) should make sure that this issue framed accurately.  The people following this thread might understand and remember, but someone coming to the issue for the first time will not.  And they might mistakenly think, as I did until recently, that you had an objection to javascript itself.

-Ivan

Re: On being web-friendly and why info must die

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> > Can we define a new type of URL to refer to a locally-installed
>>> > HTML-Info manual?
>
> I don't think that's interesting.  A more interesting URL is one that
> works both as a reference to locally-installed manuals and as
> a reference to some remote manual (when not available locally).


URLs are also URIs (and IRIs). That is the are identifiers.

There is nothing at all to prevent a web browser seeing
http://gnu.org/info/emacs/node but resolving to
/usr/share/info/emacs/node.

In fact most browsers do this, with their web cache. It's just a lazily
instantiated locally-installed manual.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Richard Stallman <rms@gnu.org> writes:
>   > Org-mode does all of that, but doesn't have to do any of that. The
>   > org-mode manual link which Achim Gratz is worth looking at.
>
> With all due respect, I don't think you have addressed the issue
> I raised.
>
> I looked at that manual text, and it doesn't do the job needed
> to use Org format as a documentation source.
>
>   > Also, it's worth noting that texinfo current disperses the documentation
>   > amount unrelated topics such as navigation.
>
> I don't follow you here.


I find texinfo a fairly busy format because of all the menus and node
information. Several people have referred to it here, so it's clearly
not just me. The semantics of navigation is not something that I care
about as an author.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Richard Stallman <rms@gnu.org> writes:
>   > I meant as a pointer. So
>
>   >     @defdocstring{current-buffer}
>
>   > would appear as 
>
>   >     Return the current buffer as a Lisp object.
>
>   > In the output format.
>
> There are two reasons we don't want to do this.
>
> 1. We want the manual text to be specified in the manual sources,
> not referred to some other file.
>
> 2. The text that makes a good doc string is not good for the manual.
>
> A feature to facilitate using the same text for both is inherently not
> a good idea.

It's probably worth looking at dash.el. The definition of -map for
instance looks like this:


-map (fn list)

Return a new list consisting of the result of applying fn to the items in list.

(-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
(-map 'square '(1 2 3 4)) ;; => '(1 4 9 16)
(--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)


After the definition there are some useful examples, which you can look
at if you do not understand the definition. And, here is the nice
thing -- these examples are actually generated from the test cases; if
the -map does not work in the way that these examples suggest the tests
will fail.

There are quite a few places where the text in the emacs manual is
similar to the docstrings. So a more programmatic documentation format
is worth thinking about.

Phil

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

David Kastrup writes:

 > This discussion seems a bit surreal since
 > 
 >     gnome-open info:emacs
 > 
 > already opens a help browser on the Emacs documentation.

OK, but "info emacs" is shorter and works on all my platforms (none of
which have gnome-open installed, all of which have info in /usr/bin,
including the BSD-based ones -- exception of course is Windows, which
isn't "my" platform and I did have to explicitly install info there).

OTOH, neither "xdg-open info:emacs" nor "open info:emacs" do anything
useful.

Note that "info" doesn't need to be info in the future; it can be a
program that does the right thing with program names (ie, translating
them to URLs to hand to a browser).

Re: On being web-friendly and why info must die

[David Kastrup]

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

> David Kastrup writes:
>
>  > This discussion seems a bit surreal since
>  > 
>  >     gnome-open info:emacs
>  > 
>  > already opens a help browser on the Emacs documentation.
>
> OK, but "info emacs" is shorter and works on all my platforms (none of
> which have gnome-open installed, all of which have info in /usr/bin,
> including the BSD-based ones -- exception of course is Windows, which
> isn't "my" platform and I did have to explicitly install info there).
>
> OTOH, neither "xdg-open info:emacs" nor "open info:emacs" do anything
> useful.

xdg-open does here (basically same as gnome-open).  And, uh, open is
something else entirely:

Usage: open [OPTIONS] -- command

This utility help you to start a program on a new virtual terminal (VT).

Options:
  -c, --console=NUM   use the given VT number;
  -e, --exec          execute the command, without forking;
  -f, --force         force opening a VT without checking;
  -l, --login         make the command a login shell;
  -u, --user          figure out the owner of the current VT;
  -s, --switch        switch to the new VT;
  -w, --wait          wait for command to complete;
  -v, --verbose       print a message for each action;
  -V, --version       print program version and exit;
  -h, --help          output a brief help message.


> Note that "info" doesn't need to be info in the future; it can be a
> program that does the right thing with program names (ie, translating
> them to URLs to hand to a browser).

Sure.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

David Kastrup writes:

 > xdg-open does [open a help browser on the Emacs manual] here
 > (basically same as gnome-open).

I wonder how what happened.  What does "ls -l `which xdg-open`" tell
you?  Or maybe there's a common database for XDG-conforming utilities?

Anyway, it's hardly reliable if it doesn't work on another distro
(I've tried on Gentoo and Debian now).

 > And, uh, open is something else entirely:

No, Mac OS X is something else entirely. ;-)

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

>> Not by itself, but with a good search engine it could. I am just
>> testing http://www.opensearchserver.com/ and I am surprised by the
>> quality and the easy of use - even locally.

> What sort of thing is that?  You referred to it with a URL; does that
> mean it is a web service?  Or is it a program?

Downloadable program (or set of programs), written in Java, under GPL v3:
 https://github.com/jaeksoft/opensearchserver/blob/master/LICENSE.txt

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Mon, 15 Dec 2014 16:47:56 +0000
> Cc: emacs-devel@gnu.org, sb@dod.no, kyle.c.andrews@gmail.com
> 
> I find texinfo a fairly busy format because of all the menus and node
> information.

The Emacs Texinfo mode makes this a non-issue.  You type a few keys,
and Emacs takes care of the rest.

Re: On being web-friendly and why info must die

[David Kastrup]

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

> David Kastrup writes:
>
>  > xdg-open does [open a help browser on the Emacs manual] here
>  > (basically same as gnome-open).
>
> I wonder how what happened.  What does "ls -l `which xdg-open`" tell
> you?

-rwxr-xr-x 1 root root 13794 Jul 16 11:43 /usr/bin/xdg-open

> Or maybe there's a common database for XDG-conforming utilities?

Isn't that sort of the point?  See, for example,

<URL:http://lilypond.org/doc/v2.18/Documentation/usage/configuring-the-system-for-point-and-click#using-gnome-3-for-point-and-click>

> Anyway, it's hardly reliable if it doesn't work on another distro
> (I've tried on Gentoo and Debian now).

Probably depends on yelp being installed.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Mon, 15 Dec 2014 16:54:32 +0000
> Cc: esr@thyrsus.com, rudalics@gmx.at, ludo@gnu.org, emacs-devel@gnu.org
> 
> There are quite a few places where the text in the emacs manual is
> similar to the docstrings.

More often than not, they need to be rewritten.

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
> If you send me a list of the current simple markup characters,
> I could make some proposals.

The simple markup is *bold*, =verbatim=, ~code~, /italic/
+strike-through+ and _underline_.  The actual rules are a bit more
complicated since some of that is costumizable for historical reasons.

The last section in the Org syntax document says this:

--8<---------------cut here---------------start------------->8---
Text Markup

Text markup follows the pattern:

PRE MARKER CONTENTS MARKER POST

PRE is a whitespace character, (, { ~’~ or a double quote. It can also be a beginning of line.

MARKER is a character among * (bold), = (verbatim), / (italic), + (strike-through), _ (underline), ~ (code).

CONTENTS is a string following the pattern:

BORDER BODY BORDER

BORDER can be any non-whitespace character excepted ~,~, ~’~ or a double quote.

BODY can contain contain any character but may not span over more than 3 lines.

BORDER and BODY are not separated by whitespaces.

CONTENTS can contain any object encountered in a paragraph when markup is “bold”, “italic”, “strike-through” or “underline”.

POST is a whitespace character, -, ., ~,~, :, !, ?, ~’~, ), } or a double quote. It can also be an end of line.

PRE, MARKER, CONTENTS, MARKER and POST are not separated by whitespace characters.

    All of this is wrong if org-emphasis-regexp-components or org-emphasis-alist are modified.

    This should really be simplified and made persistent (i.e. no defcustom allowed). Otherwise, portability and parsing are jokes.

    Also, CONTENTS should be anything within code and verbatim emphasis, by definition. — ngz
--8<---------------cut here---------------end--------------->8---

> I agree that we should not go overboard on this.  It might be good for
> 10 common constructs to have character pairs to designate them, while
> using Texinfo-like format with braces for the rest of the constructs.

I imagine that to look a lot like digraphs and trigraphs...


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
>   > Yes, but turning the tables: what exactly are the requirements for a GNU
>   > documentation format?
>
> It has to have all the features offered by Texinfo, except that if you
> can show a certain Texinfo feature is hardly ever used by GNU manuals,
> maybe it can be omitted.

So in essence you're saying that the requirement is semantic markup, but
you don't care about the syntax.  This actually rules out quite a few of
the contenders discussed in this thread.  Indeed by its very ature
semantic markup is intrusive as it often re-states something that is
obvious from context to the reader, for the sole purpose of making that
context explicit to some processing step later on.  In that case, our
efforts might be better spent in developing ways to recognize such
context and injecting the semantic markup automatically.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: On being web-friendly and why info must die

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> "Stephen J. Turnbull" <stephen@xemacs.org> writes:
>
>> David Kastrup writes:
>>
>>  > xdg-open does [open a help browser on the Emacs manual] here
>>  > (basically same as gnome-open).
>>
>> I wonder how what happened.  What does "ls -l `which xdg-open`" tell
>> you?
>
> -rwxr-xr-x 1 root root 13794 Jul 16 11:43 /usr/bin/xdg-open
>
>> Or maybe there's a common database for XDG-conforming utilities?
>
> Isn't that sort of the point?  See, for example,
>
> <URL:http://lilypond.org/doc/v2.18/Documentation/usage/configuring-the-system-for-point-and-click#using-gnome-3-for-point-and-click>
>
>> Anyway, it's hardly reliable if it doesn't work on another distro
>> (I've tried on Gentoo and Debian now).
>
> Probably depends on yelp being installed.

Oh, by the way, that's also one of the things that is great about
GNOME 3: there is no kind of documentation where such stuff may be
found.  It's basically a combination of searching for obscure Wiki pages
and blowing your top in mailing lists that helps you find out about such
stuff (the gconftool-2 recipes just stopped working at some point of
time, naturally without error messages as they did some configuration
that some old applications might still have noticed).

-- 
David Kastrup

Re: On being web-friendly and why info must die

[chad]

> On 14 Dec 2014, at 17:32, Stephen J. Turnbull <stephen@xemacs.org> wrote:
> 
> 
>> It would be interesting to see browsers and javascript packages
>> adopt a GPL-compatibility declaration,
> 
> Good luck.  The people advocating HTML are using IE, Firefox, Chrome,
> or Safari (or DFSG variants of the above, where legally feasible), I'd
> bet.  GPL browsers are minor.

I must have been unclear: I’m talking about declarations in the
javascript code that is delivered to the browser. That requires
absolutely nothing of the browser authors themselves that isnt
already long-available - you need the javascript authors to make a
GPL-compatible declaration, and then you need a browser extension
to tell the user about the declaration.  The browser extension is
an easy task for people familiar with such. Getting the javascript
package/library/framework/whatever authors to agree to the GPL is
harder.

>> There are practical ways in which users can exert some control over
>> client-side javascript today (GreaseMonkey, NoScript, and the like).
> 
> I think that's a much better approach.  I really don't care if the
> code I'm running is GPL or another FLOSS license or public domain.
> After all, the browsers I use most of the time aren't even GPL
> themselves.  I don't think crackers and phishers will hesitate to
> fraudulently present a GPL assertion, either.  So what I really want
> is a feature that tells me that I haven't run this script before and
> asks me if I want to run it.


The GPL declarations for, say, gcc, gdb, and (tentatively) emacs
all have the same problem. I am assuming that the approaches that
are acceptable there could also apply here.

Let me try this another way: the theoretical acceptable emacs FFI
adds code to emacs that checks for a GPL declaration. The technical
hurdles to having a browser plugin that does the same for
delivered-to-the-client javascript code are very low; if such a
system were desirable, the political hurdles are much harder. I
dont know if the idea is useful enough to be worth the effort in
general, but it presents a potential way past (what I believe is)
a key objection to reliance on what I had called client-side
javascript.

~Chad

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

This discussion about GPL-covered browsers and such is based on
misunderstanding what the issue is.  Some people stated guesses about
what I'm concerned about, and others are discussing those conjectured
concerns, but they are not the real concerns.

Please see the messages from me which say what the issue is.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I also object to the shortcut itself.  An accurate phrasing would be
  > "server-supplied Javascript", and I don't see why you would encourage
  > use of the rather inaccurate and misleading "client-side Javascript".

I don't.

I am simply asking you please not to focus on the side issue of
terminology.  The useful way to critiicize a misleading term is with a
suggestion for the better of talking about the real issue.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >  > We want to write something short such as `info:emacs' to refer to the
  >  > Emacs manual.

  > Why?

To make references from one HTML-Info manual to another HTML-Info
manual work properly, searching for the other manual in the right way.

	  I don't think either the browser maintainers or the IETF will be
  > particularly interested in an info: scheme since it's really a
  > document format rather than a transport.

It has nothing to do with the file format.  These files will be HTML.

Rather, it refers to a way of searching for a file (usually local,
but maybe not always).

Anyway, we don't depend on their approval.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

chad writes:

 > I must have been unclear: I’m talking about declarations in the
 > javascript code that is delivered to the browser.

That was clear.

 > That requires absolutely nothing of the browser authors themselves
 > that isnt already long-available

I believe that Richard will disagree, but we'll see.  At least IMHO:

 > - you need the javascript authors to make a GPL-compatible
 > declaration, and then you need a browser extension to tell the user
 > about the declaration.

is hardly useful, since it requires the user to install and enable the
extension.  Thus "most" users (FVO "most" > 0 :-) will not be made
aware of non-GPL Javascript (or that they're even running Javascript).

 > The GPL declarations for, say, gcc, gdb, and (tentatively) emacs
 > all have the same problem.

They have the problem of fraudulent behavior, yes.  The difference is
that from the point of view of freedom and educating users we want the
functionality built-in to the browser and enabled by default.  That is
how this is managed in the free software applications you mention.

 > I am assuming that the approaches that are acceptable there could
 > also apply here.

That depends on what you mean by "apply".  If you mean "I would like a
way to know when my browser is about to run non-free/non-GPL
software," I think that assumption is justified: it would be effective
and useful.  If you mean "would make server-supplied Javascript
acceptable to free software advocates in principle," I think there are
two major problems, one "easy", and the other not so.

(1) The popular browsers are not GPL, so GPL-compatibility
    declarations are neither meaningful nor enforceable.  (IANAL, they
    might be enforceable via "false advertising" statutes or the like,
    but certainly there's no copyright holder with standing to enforce
    GPL-ness.)  This is easy to fix, just write a world-beating web
    browser and GPL it.

(2) Even if the browser is GPL, the purpose of "the Javascript we
    hate" is to avoid the GPL.  The Javascript runs in the browser, so
    a GPL declaration would presumably be effective on that front.
    But the distributors of the Javascript who are "hiding" unfreeness
    behind an SaaS shield are on the wrong side of a network protocol
    for the GPL to take effect, and (since they are the owners of the
    Javascript) it's unlikely they'll sue themselves even if we
    strengthen the GPL-compatibility declaration to AGPL.  But nobody
    else has standing to do so AFAICS.  (Again, IANAL, but this looks
    to be a "hard" problem.)

AFAICS the best we can do is to provide a tool to help users determine
the freeness of the scripts provided by sites they visit, and provide
Javascript *with the manual sources* rather than separately via the
websites.

Re: On beincg web-friendly and why info must die

[Stephen J. Turnbull]

Richard Stallman writes:
 > [[[ To any NSA and FBI agents reading my email: please consider    ]]]
 > [[[ whether defending the US Constitution against all enemies,     ]]]
 > [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
 > 
 >   > I also object to the shortcut itself.  An accurate phrasing would be
 >   > "server-supplied Javascript", and I don't see why you would encourage
 >   > use of the reather inaccurate and misleading "client-side Javascript".
 > 
 > I don't.

Good.

 > I am simply asking you please not to focus on the side issue of
 > terminology.

I don't.

Re: On being web-friendly and why info must die

[Phillip Lord]

Achim Gratz <Stromeko@nexgo.de> writes:

> Richard Stallman writes:
>>   > Yes, but turning the tables: what exactly are the requirements for a GNU
>>   > documentation format?
>>
>> It has to have all the features offered by Texinfo, except that if you
>> can show a certain Texinfo feature is hardly ever used by GNU manuals,
>> maybe it can be omitted.
>
> So in essence you're saying that the requirement is semantic markup, but
> you don't care about the syntax.  This actually rules out quite a few of
> the contenders discussed in this thread.  Indeed by its very ature
> semantic markup is intrusive as it often re-states something that is
> obvious from context to the reader, for the sole purpose of making that
> context explicit to some processing step later on.  In that case, our
> efforts might be better spent in developing ways to recognize such
> context and injecting the semantic markup automatically.

That makes sense. An org-mode based solution would be able to
distinguish (and check) function names, so could add this semantics
easily; a fall-back macro would probably still be needed for those cases
where a function and variable name clash.

Re: On being web-friendly and why info must die

[Ludovic Courtès]

Richard Stallman <rms@gnu.org> skribis:

> It has nothing to do with the file format.  These files will be HTML.

Has IXIN been ruled out already?

AFAIK this is the only effort whose design was based on a detailed
analysis of the requirements.

There seems to be a push for a specific solution (HTML) without having
first clearly defined the requirements.

Ludo’.

URIs for GNU documentation

[Ivan Shmakov]

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

 >>> We want to write something short such as `info:emacs' to refer to
 >>> the Emacs manual.

[…]

 >> I don't think either the browser maintainers or the IETF will be
 >> particularly interested in an info: scheme since it's really a
 >> document format rather than a transport.

 > It has nothing to do with the file format.  These files will be HTML.

 > Rather, it refers to a way of searching for a file (usually local,
 > but maybe not always).

 > Anyway, we don't depend on their approval.

	The very premise of this thread was (AIUI) to make the GNU
	documentation more “Web-friendly,” which I tend to interpret to
	mean “works with any browser” (among other things.)  The use of
	a specialized, Emacs-only URI scheme would be against that goal.

	Below, I’ve tried to outline several of the available choices,
	and (hopefully) made an argument for using a standardized
	Info HTML files naming scheme to facilitate cross-references.


    URI schemes and URNs

	There’re a plenty of existing URI schemes that’d fit the role.
	The core choice to make is whether to use URNs (similar to the
	info: scheme suggested above) or URLs.

	The advantages of the former are: the URIs may be made entirely
	independent of the exact locations of the files comprising the
	documentation or section; they /could/ be concise; the existing
	infrastructure (such as XML catalogs [1], for instance) could
	probably be re-used.

	The necessity of a separately maintained mapping from names to
	locations (not unlike the currently used Info directory) is the
	principal disadvantage, – especially if it’s desired that a
	remote copy should be used when no local one is available.  The
	other disadvantage is that the use of a generic scheme either
	implies some “specialization overhead”, for instance [2, 3]:

               tag:gnu.org,2014:manual:emacs
   urn:publicid:%2B:IDN+gnu.org:Manual+GNU+Emacs+25.0.50.1:EN

	or requires the use of URIs whose intended meaning is not
	readily discernable [4, 5]:

   urn:oid:1.3.6.1.4.1.1370787.42
   urn:uuid:b36df5bb-cf0c-4e1a-acd6-dc6602e5d6a4

	As an alternative, FSF could request a separate URN namespace
	(urn:fsf:), but the use of the resulting identifiers would imply
	some kind of approval or endorsement from the Foundation, which
	seems infeasible for non-GNU projects.


    Naming scheme for Info HTML files

	The use of URLs for the purpose has the obvious drawback of them
	being tied to particular remote service or local filesystem
	layout.

	The question is: is that a problem?  The filesystem layout for
	the majority of GNU installations is already standardized; say,
	we may expect to find the Info documents somewhere under
	/usr/share/info (also /share/info for GNU/Hurd.)

	Should we take a step further and require that the HTML Info
	documentation be installed using a specific scheme, – and we
	could readily refer to a specific node or section using plain
	relative URIs.  For instance, assuming the following scheme:

   PACKAGE-VERSION/MANUAL/NODE.html

	the following translations would take place:

   doc/lispref/abbrevs.texi:
   @pxref{Expanding Abbrevs,, Expanding Abbrevs, emacs, The GNU Emacs Manual}

   /usr/share/info/emacs-25.0.50.1/elisp/Abbrevs.html:
   <a href="../emacs/Expanding-Abbrevs.html" >…</a>

   doc/lispref/building.texi:
   @xref{Top,, Make, make, GNU Make Manual}.

   /usr/share/info/emacs-25.0.50.1/elisp/Compilation.html:
   <a href="../../latest/make/index.html" >…</a>

	In the latter case, ‘latest’ could be a directory populated with
	either symbolic links pointing to the latest versions of the
	manuals, /or/ HTML redirect pages (including redirects to
	non-local copies of the documentation not currently installed.)

	Alternatively, when the manuals are served via HTTP(S), ‘latest’
	may refer to a server-side program translating the URIs it
	receives into (temporary) HTTP redirects to the fully-qualified
	locations.


    References

[1] https://oasis-open.org/committees/entity/specs/cs-entity-xml-catalogs-1.0.html
[2] https://tools.ietf.org/html/rfc4151 (urn:ietf:rfc:4151)
[3] https://tools.ietf.org/html/rfc3151 (urn:ietf:rfc:3151)
[4] https://tools.ietf.org/html/rfc3061 (urn:ietf:rfc:3061)
[5] https://tools.ietf.org/html/rfc4122 (urn:ietf:rfc:4122)

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I don't.  Yes, I want it to be "as short as possible", but I also want
  > it to work when passed to any random web-browser.
  > So it pretty much has to look like "http://<hostname>/<somethingelse>".

Whatever it looks like, it has to lead to your locally installed copy
of the manual in question.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I find texinfo a fairly busy format because of all the menus and node
  > information.

I'm sorry you dislike it, but that information has to be specified
in the manual source somehow.

  > The semantics of navigation is not something that I care
  > about as an author.

I don't understand what change you have in mind.  What we document in
the Texinfo manual is what you need to know to write that part of the
manual.  You seem to think we could omit it, but I don't see how that
could work.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > There are quite a few places where the text in the emacs manual is
  > similar to the docstrings.

They are usually _similar_ in that they give much of the same
information.  The point is that they should not be _written the same
way_.

Examples are a different issue.  It might be useful for the Emacs Lisp
manual to have a sample program in it, and arrange to be able to run
it and insert its output.

But don't focus too much on documentation of Emacs Lisp functions.
Most of our manuals are not about Emacs and have nothing to do with
Emacs Lisp functions.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >  > already opens a help browser on the Emacs documentation.

  > OK, but "info emacs" is shorter and works on all my platforms (none of
  > which have gnome-open installed, all of which have info in /usr/bin,

The crucial design question is how to represent a cross-reference from
one manual to another manual.

For the command `info', we can easily have a script to provide whatever
interface we like.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Downloadable program (or set of programs), written in Java, under GPL v3:
  >  https://github.com/jaeksoft/opensearchserver/blob/master/LICENSE.txt

That means it's ok for us to use, if it is useful.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The simple markup is *bold*, =verbatim=, ~code~, /italic/
  > +strike-through+ and _underline_.  The actual rules are a bit more
  > complicated since some of that is costumizable for historical reasons.

Here's one way it could be done:

//emph//
/=dfn=/
==code==
'=samp='
.=file=.
_kbd_
*strong*
@variable@

(We don't need strike-through or underline.)

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > So in essence you're saying that the requirement is semantic markup, but
  > you don't care about the syntax.

This is an interesting question.

In the past, semantic markup was absolutely necessary.  For instance,
@dfn and @emph both generate italic in TeX, but they appear different
in Info.  This was because Info files don't have fonts.  Distinctions need
to be made some other way.

I have been assuming this is still necessary, but maybe it is not.
If HTML-Info can represent these distinctions with fonts, the same
as in TeX, maybe we don't need semantic markup any more.  Maybe
the same appearance can be used in all formats on line and on paper.

But how would we represent them on a tty?  They have colors but no fonts.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > If someone takes a verbal shortcut and refers to that problem by
  > > saying "client-side Javascript", would you please keep in mind that
  > > the real issue is what I stated in the paragraph above?

  > If you keep in mind that when I say Linux, I mean GNU/Linux.  :-)

I know that -- but calling it "Linux" is mistreating  us, giving the
credit for our work to Mr Torvalds.  Therefore, even though I know
what you mean, I will ask you to recognize our work.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Yuri Khan]

On Wed, Dec 17, 2014 at 9:30 AM, Richard Stallman <rms@gnu.org> wrote:

> I have been assuming this is still necessary, but maybe it is not.
> If HTML-Info can represent these distinctions with fonts, the same
> as in TeX, maybe we don't need semantic markup any more.  Maybe
> the same appearance can be used in all formats on line and on paper.

Appearance is not everything. As a user of a hypothetical HTML-Info, I
want to be able to restyle (customize the appearance of) elements with
different semantics differently and conveniently. That requires
semantic HTML (either with semantic HTML elements such as <kbd>, <em>
and <code> or with CSS classes where no directly suitable element is
available). And that, in turn, requires either semantic source or a
magic semantic-deriving preprocessor.

Now I have been involved in several magic semantic-deriving projects,
and I tell you, it’s not a pretty job.

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

>> I don't.  Yes, I want it to be "as short as possible", but I also
>> want it to work when passed to any random web-browser.
>> So it pretty much has to look like "http://<hostname>/<somethingelse>".

> Whatever it looks like, it has to lead to your locally installed copy
> of the manual in question.

FWIW, a relative local path, eg. "../chap1.html", is also a legal URI
reference: https://tools.ietf.org/html/rfc3986#appendix-A

All existing web browsers will respect this.

Re: On being web-friendly and why info must die

[Thien-Thi Nguyen]

[-- Attachment #1.1: Type: text/plain, Size: 205 bytes --]

() ludo@gnu.org (Ludovic Courtès)
() Tue, 16 Dec 2014 16:57:01 +0100

   Has IXIN been ruled out already?

Probably the README is not enticing enough for Emacs hackers.
Maybe this patch will help:

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: marketing.diff --]
[-- Type: text/x-diff, Size: 740 bytes --]

commit b70b103663478a3dc1a0134418b950e67303893b
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
Date:   2014-12-17 09:35:56 +0100

    [maint] Mention p-o-c rendering program domain in README; nfc.
---
 README | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README b/README
index 5625597..8f9f8cb 100644
--- a/README
+++ b/README
@@ -14,6 +14,7 @@ See end for copying conditions.
 
   [[file:c/]] contains some simple command-line utilities to write and
   read the file format, and a proof-of-concept rendering program.
+  (Think of it as a potential info.el replacement for Emacs.)
 
   [[file:d/]] contains the some pre-built .sxml and .ixin files.
   [[file:d/GNUmakefile]] supports "make demo" and "make demo-zow",

[-- Attachment #1.3: Type: text/plain, Size: 1037 bytes --]


I will add some more marketing in README and release 1.9, which
will include the following changes, shortly:

 b70b103 2014-12-17 [maint] Mention p-o-c rendering program domain in README; nfc.
 6c75fc1 2013-07-24 [maint] Reformat NEWS; nfc.
 01e430d 2013-02-18 No longer distribute {epsf,texinfo}.tex.
 9ba97fe 2013-02-18 [spec int] Fix typo: Include "(news)" heading.

The "IX" in "IXIN" stands for "indexed", the most important
piece of metainfo in a manual, IMHO.  A high-quality index
communicates the authors' priorities and intent; those who
consult/browse it save time and gain aligned perspective.

I think any proposed info format replacement that demotes
index support to second-class is a dissipative WOMBAT at best.
To me, "second-class" includes remote (server) protocols, etc.

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: On being web-friendly and why info must die

[Steinar Bang]

>>>>> Richard Stallman <rms@gnu.org>:

> Examples are a different issue.  It might be useful for the Emacs Lisp
> manual to have a sample program in it, and arrange to be able to run
> it and insert its output.

That's (at least) one place where Org-mode will shine: the code example
can be edited natively in the emacs lisp mode, and tested directly from
there. 

(my opinion on this entire thread, is that I don't see the big need for
replacing Texinfo, but _if_ Texinfo is to be replaced then org-mode
should be considered as the replacement)

Re: On being web-friendly and why info must die

[Alan Mackenzie]

Hello, Richard.

On Tue, Dec 16, 2014 at 10:30:40PM -0500, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]

>   > The simple markup is *bold*, =verbatim=, ~code~, /italic/
>   > +strike-through+ and _underline_.  The actual rules are a bit more
>   > complicated since some of that is costumizable for historical reasons.

> Here's one way it could be done:

> //emph//
> /=dfn=/
> ==code==
> '=samp='
> .=file=.
> _kbd_
> *strong*
> @variable@

Please don't go for something like this.  It is too confusing for
somebody like me, who couldn't possibly remember all these variations
from one document-writing session to the next.  There is nothing mnemonic
about any of these markups, unlike the Texinfo @emph{foo}, etc.

I would find this a strong put-off to writing documentation.  It would
just be too much effort.  Even if there were nice key sequences, like C-c
C-c C-e, to insert these, it would still be too much strain, since there
would be no feedback that the correct C-c C-c ... sequence was used.

> (We don't need strike-through or underline.)

> -- 
> Dr Richard Stallman

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: On being web-friendly and why info must die

[Stephen J. Turnbull]

Alan Mackenzie writes:

 > I would find this a strong put-off to writing documentation.  It would
 > just be too much effort.

Hear, hear!  I'll buy you a beer (or beverage of your choice) for that!

 > Even if there were nice key sequencises, like C-c C-c C-e, to insert
 > these, it would still be too much strain, since there would be no
 > feedback that the correct C-c C-c ... sequence was used.

I'd prefer AUCTeX keystrokes (prefix C-c C-f, I guess for "face").  I
don't often make mistakes with those, even in Texinfo (where there are
a bunch of potentially confusing C-, Sh-, bare character clusters).

YMMV, I'm just another data point along the road.

Re: On being web-friendly and why info must die

[Phillip Lord]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > I find texinfo a fairly busy format because of all the menus and node
>   > information.
>
> I'm sorry you dislike it, but that information has to be specified
> in the manual source somehow.

No, it really doesn't.

>
>   > The semantics of navigation is not something that I care
>   > about as an author.
>
> I don't understand what change you have in mind.  What we document in
> the Texinfo manual is what you need to know to write that part of the
> manual.  You seem to think we could omit it, but I don't see how that
> could work.

Well, Eli says that this is a non-issue because Emacs can put it in
place with a few keypresses. Okay, well, why does Emacs have to do it?
Why does texinfo not do the job? 

Consider this snippet....

@node Abbrevs
@chapter Abbrevs

  A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
it, into some different text. 

@menu
* Abbrev Concepts::   Fundamentals of defined abbrevs.
* Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
@end menu

@node Abbrev Concepts
@section Abbrev Concepts

  An @dfn{abbrev} is a word that has been defined to @dfn{expand} into
a specified @dfn{expansion}.


In org this would be:

* Abbrevs

A defined \abbrev\ is a word which \expands\, if you insert it into some
different text.

** Abbrev Concepts

An \abbrev\ is a word that has been defined to \expand\ into a
specificed \expansion\.


Now, I agree that the loss of semantics from @dfn is not good. But org
(or markdown or asciidoc or latex) can work out the navigation from the
document structure.

Phil

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> I don't.  Yes, I want it to be "as short as possible", but I also want
>> it to work when passed to any random web-browser.
>> So it pretty much has to look like "http://<hostname>/<somethingelse>".
> Whatever it looks like, it has to lead to your locally installed copy
> of the manual in question.

That's right.  The specific <hostname> and <somethingelse> chosen should
be known to the Info reader so it can redirect the request to the
local copy.


        Stefan

Re: On being web-friendly and why info must die

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> I don't.  Yes, I want it to be "as short as possible", but I also want
>>> it to work when passed to any random web-browser.
>>> So it pretty much has to look like "http://<hostname>/<somethingelse>".
>> Whatever it looks like, it has to lead to your locally installed copy
>> of the manual in question.
>
> That's right.  The specific <hostname> and <somethingelse> chosen should
> be known to the Info reader so it can redirect the request to the
> local copy.


All that is needed for this is to use permanent, never changing URLs at
the server.

http://www.gnu.org/emacs/24.4/top

Then, a locally installed Emacs needs a mapping file (or function), so
that this URL redirects to

/usr/share/info/emacs/24.4/top

Obviously, in the source format, this means that interlinks must NOT be
full URLs -- otherwise all of the doc will have to updated every
release.

This would also give the possibility to present multiple links. So, on
seeing a link like:

http://www.gnu.org/emacs/24.4/top

the info browser would by default redirect to the 24.4 documentation
(locally), but could also signal that a new version was available,
regardless of whether it was installed locally or not.

Phil

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Wed, 17 Dec 2014 12:03:02 +0000
> Cc: kyle.c.andrews@gmail.com, sb@dod.no, emacs-devel@gnu.org
> 
> >   > I find texinfo a fairly busy format because of all the menus and node
> >   > information.
> >
> > I'm sorry you dislike it, but that information has to be specified
> > in the manual source somehow.
> 
> No, it really doesn't.

I think you only say that because you consider a subset of Texinfo's
capabilities wrt document structuring, and/or assume that such a
subset is all that's needed.  See below.

> Well, Eli says that this is a non-issue because Emacs can put it in
> place with a few keypresses. Okay, well, why does Emacs have to do it?
> Why does texinfo not do the job? 

It does.

> Consider this snippet....
> 
> @node Abbrevs
> @chapter Abbrevs
> 
>   A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
> it, into some different text. 
> 
> @menu
> * Abbrev Concepts::   Fundamentals of defined abbrevs.
> * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
> @end menu
> 
> @node Abbrev Concepts
> @section Abbrev Concepts
> 
>   An @dfn{abbrev} is a word that has been defined to @dfn{expand} into
> a specified @dfn{expansion}.
> 
> 
> In org this would be:
> 
> * Abbrevs
> 
> A defined \abbrev\ is a word which \expands\, if you insert it into some
> different text.
> 
> ** Abbrev Concepts
> 
> An \abbrev\ is a word that has been defined to \expand\ into a
> specificed \expansion\.
> 
> 
> Now, I agree that the loss of semantics from @dfn is not good. But org
> (or markdown or asciidoc or latex) can work out the navigation from the
> document structure.

So does 'makeinfo', but I guess you are not aware of that.  I explain
a little bit of that below, but there's more to Texinfo than meets the
eye, so you are encouraged to study it in more detail, because IMO
criticizing Texinfo without detailed knowledge of its features frankly
doesn't feel right.

What you wrote above in Org format defines a chapter and its
subordinate section.  And that's the _only_ structure supported by the
above paradigm: a tree, whereby the child nodes must immediately
follow their parents, in the depth-first order.

By contrast, Texinfo manuals do not have to have a tree structure.
Their structure can be an arbitrary graph.  At least one popular Info
manual (info.info) actually uses this feature: it doesn't present a
tree-like structure, but instead has a cycle or two within it.

_That_ is why there are node pointers in Texinfo.  And what the Emacs
commands I briefly mentioned do is create them automatically on the
assumption that the manual structure is indeed a simple tree.
Moreover, as long as the structure is indeed a tree, and the menus
(see below) are correctly written in each parent node naming its child
nodes, the Prev/Next/Up node pointers are not needed at all, because
'makeinfo' will deduce them automatically, and also validate the
document structure as a nice bonus.

As for menus, they provide one more degree of freedom for arranging a
manual in a non-tree structure: each menu item is a link to another
node, and can in general lead anywhere, including to another manual.

AFAIK, to do that in Org, you need to create a link; the outline-style
document you show above won't cut it.  IOW, Org requires you in that
case to insert links very similar to Texinfo menus.

As with node pointers, the Emacs Texinfo mode commands can
automatically create the menus as well, again on the assumption that
the section nodes immediately following a chapter node are child nodes
of that chapter, recursively.  Thus, in simple tree-like documents,
generating these menus is a keystroke away.

So, as you see, both Org and Texinfo solve the same problems, and they
do that in similar, albeit different, ways.  I see no advantage to Org
methods here, as long as you consider Texinfo together with its Emacs
support.  On the contrary, I see an advantage to Texinfo, because it
can easily express non-tree structured documents, something that in
Org is not so easy, perhaps even not easy at all.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

We already have software to verify that js code is free software:
LibreJS.  Anyway, that is a tangent; let's not go down that tangent
here.
-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Has IXIN been ruled out already?

A week ago I said:

    Could someone who understands Info please review it thoroughly and
    comment?

I am still waiting for this.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Appearance is not everything. As a user of a hypothetical HTML-Info, I
  > want to be able to restyle (customize the appearance of) elements with
  > different semantics differently and conveniently.

I have nothing against it -- but I don't think it is a crucial
functionality.  We do not need to reject documentation formats that
don't support it.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > //emph//
  > > /=dfn=/
  > > ==code==
  > > '=samp='
  > > .=file=.
  > > _kbd_
  > > *strong*
  > > @variable@

  > Please don't go for something like this.  It is too confusing for
  > somebody like me, who couldn't possibly remember all these variations
  > from one document-writing session to the next.

Either we use semantic markup or we use simple fixed markup.

If we need semantic markup, we can either stick with Texinfo-like
syntax or move to a syntax like what I suggested.  (I think you would
remember these commands.)

Maybe we don't meed semantic markup, if we can work out how to handle
display on a tty.  If we don't need semantic markup, we can use the
simple markup as in /italic/ and *bold*.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > FWIW, a relative local path, eg. "../chap1.html", is also a legal URI
  > reference: https://tools.ietf.org/html/rfc3986#appendix-A

Info manuals are not all stored in one directory.  They are found in a
path.  Thus, a reference to another manual has to search the path.

We could modify our browser IceCat to recognize a ../ URL in some
specific context and search the path to find the proper manual.  That
sort of URL would not work right in other browsers.

We could also make our browser IceCat handle URLs like 'info:glibc'.
Again, that would not work right in other browsers.

I don't see any advantage in the ../ URL over the 'info:' URL,
if either one would work only in our browser.

We can ask other browser developers to support either one,
but I think our chances of getting them to agree are higher with 'info:'
because that is clean.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
>   > So in essence you're saying that the requirement is semantic markup, but
>   > you don't care about the syntax.
>
> This is an interesting question.
>
> In the past, semantic markup was absolutely necessary.  For instance,
> @dfn and @emph both generate italic in TeX, but they appear different
> in Info.  This was because Info files don't have fonts.  Distinctions need
> to be made some other way.
>
> I have been assuming this is still necessary, but maybe it is not.

I'd say that given your goals semantic markup is still necessary.
Visual markup that somehow by convention doubles as semantic markup
isn't a proper solution.  It will work often enough to be attractive in
the beginning and won't work often enough to be annoying in the long
run.

I think we need to make a three-fold distinction between the format that
the documentation should be in (something standardized might be nice),
the presentation of the documentation to the target audience (needs at
least a handful of options) and the various ways to create content in
this format.  As said before, I don't think it is necessary to require
each and every contributor to fully understand the intricacies of
semantic markup if there's an easy (or easier at least) input method
that keeps the markup in the background for most of the editing.  THat
method need not be perfect if any wrong guesses as to what the proper
context is can easily be overridden.

> If HTML-Info can represent these distinctions with fonts, the same
> as in TeX, maybe we don't need semantic markup any more.  Maybe
> the same appearance can be used in all formats on line and on paper.

I would like to eradicate the idea that somehow fonts or colors are
going to be part of the markup or an indispensable part of the output.
Styling by using fonts and colors is a good way to clarify meaning to
many users, but we shouldn't forget about those users who simply can't
use these two as a distinction for whatever reason.

> But how would we represent them on a tty?  They have colors but no fonts.

A braille line has no fonts nor colors.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: On being web-friendly and why info must die

[Achim Gratz]

Richard Stallman writes:
>   > The simple markup is *bold*, =verbatim=, ~code~, /italic/
>   > +strike-through+ and _underline_.  The actual rules are a bit more
>   > complicated since some of that is costumizable for historical reasons.
>
> Here's one way it could be done:
>
> //emph//
> /=dfn=/
> ==code==
> '=samp='
> .=file=.
> _kbd_
> *strong*
> @variable@
>
> (We don't need strike-through or underline.)

Org uses regex parsing for most of this stuff, so good performance very
much requires that you don't need to backtrack often.  These suggestions
would work for proper (tokenized) parsing, but are most likely not
acceptable for Org (something like this has been tried before I should
add).

Besides, I don't really think that this suggestion fulfills the goal of
having easily discernible semantic markup.  It's deeply magical, awkward
to type in some keyboard layouts and hard to read in a variety of fonts.
I guess that a lot of contributors would simply cargo-cult this markup
into the documentation without ever knowing what they are doing.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for KORG EX-800 and Poly-800MkII V0.9:
http://Synth.Stromeko.net/Downloads.html#KorgSDada

Re: On being web-friendly and why info must die

[David Kastrup]

Achim Gratz <Stromeko@nexgo.de> writes:

> Besides, I don't really think that this suggestion fulfills the goal
> of having easily discernible semantic markup.  It's deeply magical,
> awkward to type in some keyboard layouts and hard to read in a variety
> of fonts.  I guess that a lot of contributors would simply cargo-cult
> this markup into the documentation without ever knowing what they are
> doing.

That's likely happening with Texinfo as well, but at least the names are
somewhat descriptive.

-- 
David Kastrup

Re: On being web-friendly and why info must die

[Thien-Thi Nguyen]

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

() Richard Stallman <rms@gnu.org>
() Wed, 17 Dec 2014 10:44:25 -0500

   I am still waiting for this.

Authoring IXIN, i developed a moderate (by no means
comprehensive) understanding of Info (format and .el),
so the following comment is obviously biased, and
(sorry, no time) not a thorough review as requested:

 The IXIN format maintains all the semantic features
 and drops most of the layout features of the Info
 format, being essentially a re-arranged parse tree
 dump (in Lisp- and Scheme-friendly sexps) of the
 Texinfo input.  Unhandled layout features are left
 to the renderer.

 The IXIN tarballs specify this format and include a
 proof-of-concept renderer (for Emacs, of course :-D).

 IXIN is mellifluous to hack.  <-- NB: UNABASHED BIAS!

For details, i suggest reading The IXIN Chronicles,
which can be found in the release tarball (in subdir
spec/).  To grab the latest (2013-02-16) release:

 wget http://www.gnuvola.org/software/ixin/ixin-1.8.tar.xz

I will post a brief announcement when 1.9 becomes available.

Anyway, i welcome additional review / critique from
others; no doubt there's much room for improvement.
     
-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Consider this snippet....

  > @node Abbrevs
  > @chapter Abbrevs

Nodes and sections typically go together
but not always.

It is true we could make the usual case simpler by changing the
defaults.

  >   A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
  > it, into some different text. 

  > @menu
  > * Abbrev Concepts::   Fundamentals of defined abbrevs.
  > * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
  > @end menu

This is like the above issue: in the usual case, the node names in the menu
can be deduced from the rest of the document, but there are menus which
differ from that.

However, the second part of each line (the text like "Fundamentals of
defined abbrevs") can't be found anywhere else.

If it were not for that text, I could envision defining a command

  @defaultmenu

that it would generate the contents of the menu based on the document
section structure.  But where would it get that added text from?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Stefan Monnier]

>> @node Abbrevs
>> @chapter Abbrevs
> Nodes and sections typically go together but not always.
> It is true we could make the usual case simpler by changing the
> defaults.

Further than that I think it would be worth analyzing the cases where
the @nodes can't be automatically inferred from the @chapters/@sections,
and try and figure out how to handle them (or whether it's worth the
trouble) without using an explicit @node.

>> @menu
>> * Abbrev Concepts::   Fundamentals of defined abbrevs.
>> * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
>> @end menu
> This is like the above issue: in the usual case, the node names in the menu
> can be deduced from the rest of the document, but there are menus which
> differ from that.

Here as well, I think it'd would be worthwhile to analyze the existing
cases where the node names in the menu can't be deduced from the rest of
the document, and try to see how we could handle them without having to
have explicit menus or even if it's worth the trouble supporting those
at all.

> However, the second part of each line (the text like "Fundamentals of
> defined abbrevs") can't be found anywhere else.

Here, rather than suggest to analyze the existing cases, I'll just point
out that pretty much the rest of the world lives happily without being
able to use two different texts, so I'm not sure it's worth the trouble.

> section structure.  But where would it get that added text from?

If we really want to have 2 different ways to describe the node in the
menu, we could use "the node name" and "the section title".
Currently, Texinfo has typically 3 different descriptions for every
node:

   @menu
   * <NodeName>::        <MenuDescription>
   @end menu

   ...

   @node <NodeName>
   @section <SectionTitle>

in 99% of the cases, we could use the exact same text for <NodeName>,
<MenuDescription>, and <SectionTitle>.  But in 100% of the cases, we
could at least drop one of the three.


        Stefan

Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 18 Dec 2014 09:14:27 -0500
> Cc: emacs-devel@gnu.org, Phillip Lord <phillip.lord@newcastle.ac.uk>, sb@dod.no,
> 	kyle.c.andrews@gmail.com
> 
> >> @node Abbrevs
> >> @chapter Abbrevs
> > Nodes and sections typically go together but not always.
> > It is true we could make the usual case simpler by changing the
> > defaults.
> 
> Further than that I think it would be worth analyzing the cases where
> the @nodes can't be automatically inferred from the @chapters/@sections,
> and try and figure out how to handle them (or whether it's worth the
> trouble) without using an explicit @node.

We can do that by removing markup from the section names.

> >> @menu
> >> * Abbrev Concepts::   Fundamentals of defined abbrevs.
> >> * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
> >> @end menu
> > This is like the above issue: in the usual case, the node names in the menu
> > can be deduced from the rest of the document, but there are menus which
> > differ from that.
> 
> Here as well, I think it'd would be worthwhile to analyze the existing
> cases where the node names in the menu can't be deduced from the rest of
> the document

You mean, like texinfo-make-menu?

> and try to see how we could handle them without having to
> have explicit menus or even if it's worth the trouble supporting those
> at all.

Having menus is not a requirement, you can do without them.

> > However, the second part of each line (the text like "Fundamentals of
> > defined abbrevs") can't be found anywhere else.
> 
> Here, rather than suggest to analyze the existing cases, I'll just point
> out that pretty much the rest of the world lives happily without being
> able to use two different texts, so I'm not sure it's worth the trouble.

Again, it's not a requirement.  If you want to add descriptive text,
you can; but you don't have to.

Re: On being web-friendly and why info must die

[Lennart Borgman]

On Dec 12, 2014 5:41 PM, "Richard Stallman" <rms@gnu.org> wrote:
>
>   > Not by itself, but with a good search engine it could. I am just
>   > testing http://www.opensearchserver.com/ and I am surprised by the
>   > quality and the easy of use - even locally.
>
> What sort of thing is that?  You referred to it with a URL; does that
> mean it is a web service?  Or is it a program?

It is both. As a program I think it is GPL, based on Apache Lucene.
Written in Java.

The web service is not free, but you can set up your own.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Here, rather than suggest to analyze the existing cases, I'll just point
  > out that pretty much the rest of the world lives happily without being
  > able to use two different texts, so I'm not sure it's worth the trouble.

It is not actually much trouble.  If it takes two minutes for each new
node (that's estimating high), it is tiny compared with writing the
text of that node.

  > in 99% of the cases, we could use the exact same text for <NodeName>,
  > <MenuDescription>, and <SectionTitle>.

Purpose-written text in the MenuDescription is helpful to users.

In practice, usually the NodeName and SectionTitle are the same.
But often it is better if they are different.  We like node names
to be quite short, but SectionTitle can be longer.

This is due to the details of Info format.  If we replace
Info with some other format, maybe it will be fine always
to have NodeName and SectionTitle the same.

There are some cases of sections that don't have nodes,
but they could be handled specially.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:
>> In org this would be:
>> 
>> * Abbrevs
>> 
>> A defined \abbrev\ is a word which \expands\, if you insert it into some
>> different text.
>> 
>> ** Abbrev Concepts
>> 
>> An \abbrev\ is a word that has been defined to \expand\ into a
>> specificed \expansion\.
>> 
>> 
>> Now, I agree that the loss of semantics from @dfn is not good. But org
>> (or markdown or asciidoc or latex) can work out the navigation from the
>> document structure.
>
> So does 'makeinfo', but I guess you are not aware of that.  I explain
> a little bit of that below, but there's more to Texinfo than meets the
> eye, so you are encouraged to study it in more detail, because IMO
> criticizing Texinfo without detailed knowledge of its features frankly
> doesn't feel right.

Indeed, you are correct, I have never used texinfo in anger and am not
an expert at it's use. I've used asciidoc extensively, and org-mode a
reasonable amount. It's just the way that it is -- you can't be an
expert at everything.


> What you wrote above in Org format defines a chapter and its
> subordinate section.  And that's the _only_ structure supported by the
> above paradigm: a tree, whereby the child nodes must immediately
> follow their parents, in the depth-first order.
>
> By contrast, Texinfo manuals do not have to have a tree structure.
> Their structure can be an arbitrary graph.  At least one popular Info
> manual (info.info) actually uses this feature: it doesn't present a
> tree-like structure, but instead has a cycle or two within it.

I guessed that this would be case, but wasn't sure whether it was used
or not. Actually, I even implemented a feature like this for Emacs Muse
several years ago, because I needed info like next/prev functionality.
The node information was stored in a data structure which could support
an arbitary graph.

In all the time that I had this capability, I never used it to represent
anything other than a tree. The problem is, of course, that users are
not going to expect this kind of behaviour: next/prev should move, well,
next and previous. In the end, I put a facade over the graph data
structure which only allowed trees.

So, I am not convinced this is much in the way of a feature, even if
info.info uses it.

> AFAIK, to do that in Org, you need to create a link; the outline-style
> document you show above won't cut it.  IOW, Org requires you in that
> case to insert links very similar to Texinfo menus.

Sure. Navigation menus happen automatically. Then there are hyperlinks,
and see also links.


> As with node pointers, the Emacs Texinfo mode commands can
> automatically create the menus as well, again on the assumption that
> the section nodes immediately following a chapter node are child nodes
> of that chapter, recursively.  Thus, in simple tree-like documents,
> generating these menus is a keystroke away.

And, in non-simple tree-like documents they are not. Which probably
means that the non-simple tree-like documents are rarely written.

> So, as you see, both Org and Texinfo solve the same problems, and they
> do that in similar, albeit different, ways.  I see no advantage to Org
> methods here, as long as you consider Texinfo together with its Emacs
> support.

I'm just struggling to think of another document format with explicit
menu navigation in the source. To me, it does not make sense to have a
source format within knowledge that could be infered out; it's more
error prone, but also less semantic. In so far as possible, I think,
navigation be a feature of the representation, not the source.


> On the contrary, I see an advantage to Texinfo, because it can easily
> express non-tree structured documents, something that in Org is not so
> easy, perhaps even not easy at all.

As you will.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Richard Stallman <rms@gnu.org> writes:

>   > @menu
>   > * Abbrev Concepts::   Fundamentals of defined abbrevs.
>   > * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
>   > @end menu
>
> This is like the above issue: in the usual case, the node names in the menu
> can be deduced from the rest of the document, but there are menus which
> differ from that.
>
> However, the second part of each line (the text like "Fundamentals of
> defined abbrevs") can't be found anywhere else.
>
> If it were not for that text, I could envision defining a command
>
>   @defaultmenu
>
> that it would generate the contents of the menu based on the document
> section structure.  But where would it get that added text from?

I would put that text near the node definition. Kind of similar to latex
where you put the title and the running head together. Of course, this
means if you have a node in two menus it must have the same long text,
but also, it means that you don't have to have the same text twice.

To me, it makes more sense to include all the information about a page
in one place, under the control of the author of this page.

Phil

Re: On being web-friendly and why info must die

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> However, the second part of each line (the text like "Fundamentals of
>> defined abbrevs") can't be found anywhere else.
>
> Here, rather than suggest to analyze the existing cases, I'll just point
> out that pretty much the rest of the world lives happily without being
> able to use two different texts, so I'm not sure it's worth the trouble.

Or alternatively, I would ask, iff the extra text is worth seeing in a
menu item point to a page, why it is also not worth seeing in the page
itself. 

Menu:
 Abbrevs Concepts: Fundamentals of defined abbrevs

Should open to a page

Fundamentals of defined abbrevs
(Abbrevs Concepts).

I might even go further and just drop the Node node which is perhaps a
form of explicit navigation that we are infliciting of the user.


Why not have a visualisation that looks like:

Menu:
   - The Fundamentals of defined Abbrevs


And points to a node

The fundamentals of defined abbrevs.

"Abbrev Concepts" gets relegated to the role of the anchor text, just
used for linking the two together. Visible to the developer only.

Phil

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The web service is not free,

What do you think it means to say a web service is free or not?
We have no definition for that.  We don't use that terminology.

Our definition of "free" makes sense for _works_, not for services.
See http://www.gnu.org/philosophy/network-services-arent-free-or-nonfree.html.
Services raise totally different issues.

Therefore, I urge people NOT to call any service "free" or
"proprietary".  It causes confusion.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Getting to online manuals from Info [was: On being web-friendly...]

[Drew Adams]

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

> > I frequently point people to particular nodes of our online HTML
> > manuals that could answer their question.  The way I do that is
> > to find the information in Info, then copy&paste some recognizably
> > unique text phrase into a web search engine, check that the
> > reference this turns up is the corresponding online version of
> > the Info manual and then post the HTML link.
> 
> Same here.  Except I don't bother to search the web.  I just go
> to the GNU Emacs or Elisp manual on the web (separate HTML page
> per node version), search the TOC (first page) for the node name,
> and copy the URL of the link to that node.
> 
> I do this often.  Instead of just answering questions, it is
> most helpful to *point users to the doc*, so they get additional
> info and they get the benefit of well thought out presentation.
> 
> It is even more helpful to also to tell them how _they_ can find
> such doc, by *asking Emacs* directly.
> 
> Probably what I should do is write an Emacs command that does
> all of that from an Info node: grab the URL to that same manual
> node on the web.  But it's so quick to get it manually that I
> haven't bothered, so far.

FWIW, attached is simple POC code to do this.  It handles only
the Emacs and Elisp manuals, but it could be extended to other
GNU manuals.  (The main use case for me is that expressed above.)

Two commands, for use in Info:

`Info-url-for-node':  Prompts for a node name and returns a URL
                      to that node on line.  Interactively, it
                      copies the URL to the `kill-ring'.

`Info-goto-node-web': Prompts for a node name and goes to that
                      node on line.

[-- Attachment #2: throw-manual-web.el --]
[-- Type: application/octet-stream, Size: 2405 bytes --]

(defun Info-goto-node-web (node &optional flip-new-win)
  "Use `browse-url' to go to Info node NODE using a Web browser.
With a prefix arg, reverse the effect of option
option`browse-url-new-window-flag'.

NODE is the name of a node in the GNU Emacs or Elisp manual.
Alternatively, NODE can have the form (MANUAL)NODE, where MANUAL is
\"emacs\" or \"elisp\" and NODE is the name of the node in that
manual.  Empty NODE in (MANUAL) defaults to the `Top' node."
  (interactive (list (Info-read-node-name "Go to node: ") current-prefix-arg))
  ;; (info-initialize)
  (unless Info-current-file (error "This command must be invoked from Info"))
  (browse-url (Info-url-for-node node) (list (if flip-new-win
                                                 (not browse-url-new-window-flag)
                                               browse-url-new-window-flag))))

(defun Info-url-for-node (node &optional copy-as-kill)
  "Return a URL for NODE, a node in the GNU Emacs or Elisp manual.
Alternatively, NODE can have the form (MANUAL)NODE, where MANUAL is
\"emacs\" or \"elisp\" and NODE is the name of the node in that
manual.  Empty NODE in (MANUAL) defaults to the `Top' node.
Interactively, the URL is copied to `kill-ring', so you can yank it."
  (interactive (list (Info-read-node-name "Node: ") 'COPY))
  (unless Info-current-file (error "This command must be invoked from Info"))
  (let (file url)
    (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)" node)
    (setq file  (if (= (match-beginning 1) (match-end 1)) "" (match-string 2 node))
	  node  (match-string 3 node))
    (when (equal node "") (setq node  "index")) ; `Top' node.
    (let ((trim  (string-match "\\s +\\'" file)))
      (when trim (setq file (substring file 0 trim))))
    (let ((trim  (string-match "\\s +\\'" node)))
      (when trim (setq node (substring node 0 trim))))
    (when (equal file "") (setq file  Info-current-file))
    (setq file  (file-name-sans-extension (file-name-nondirectory file)))
    (unless (member file '("emacs" "elisp"))
      (error "Manual cannot be `%s'; it can only be `emacs' or `elisp'" file))
    (setq node  (replace-regexp-in-string "[ \t]+" "-" node t t)
          url       (concat "http://www.gnu.org/software/emacs/manual/html_node/"
                            file "/" node ".html"))
    (when copy-as-kill (kill-new url) (message "URL copied: %s" url))
    url))

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > A braille line has no fonts nor colors.

Maybe that means we should not try to represent markup in braille.  We
never made that a goal.

However, we do represent markup on a tty, in Emacs and in the standalone
Info reader.  I don't want to abandon that functionality (which I use).

This is one argument for keeping semantic markup.

However, we could still replace Info format with some other format
that is more powerful and/or more widely supported, such as HTML-Info.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I would put that text near the node definition.

In principle I have nothing against it.


  > Or alternatively, I would ask, iff the extra text is worth seeing in a
  > menu item point to a page, why it is also not worth seeing in the page
  > itself. 

  > Menu:
  >  Abbrevs Concepts: Fundamentals of defined abbrevs

  > Should open to a page

  > Fundamentals of defined abbrevs
  > (Abbrevs Concepts).

In Info the node will display, as a title, the section name
which can be different from those two.

At present, in that node, the section name is "Abbrev Concepts",
same as the node name.  But we could use a longer title such as
"Fundamental Concepts of Abbrevs".  That might be an improvement.

That's the reason why the section title can be different from the node
name.

The node name should be a terse stand-alone description of the node's
topic.

The section title should also be a stand-alone description of the
node's topic, but can be longer.

The added text on the menu line is meant to supplement the node name
with more information about that node.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: On being web-friendly and why info must die

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

   > The IXIN format maintains all the semantic features
   > and drops most of the layout features of the Info
   > format, being essentially a re-arranged parse tree
   > dump (in Lisp- and Scheme-friendly sexps) of the
   > Texinfo input.  Unhandled layout features are left
   > to the renderer.

I think I understand this now.

It could be a good distribution format for use by a specialized Info
reader, but would not be usable by ordinary web browsers.

Thus, I think it is still a good idea to develop an HTML-Info format
that would be usable by ordinary web browsers, but would have stylized
constructions so that a specialized or customized browser could provide
all the user-level features of an Info browser.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: URIs for GNU documentation

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

     > 	or requires the use of URIs whose intended meaning is not
     > 	readily discernable [4, 5]:

     > urn:oid:1.3.6.1.4.1.1370787.42
     > urn:uuid:b36df5bb-cf0c-4e1a-acd6-dc6602e5d6a4

I don't know what those things mean, so I can't evaluate whether
they would work for this job.

	  > The question is: is that a problem?  The filesystem layout for
	  > the majority of GNU installations is already standardized; say,
	  > we may expect to find the Info documents somewhere under
	  > /usr/share/info (also /share/info for GNU/Hurd.)

Those places are used currently for manuals installed at system level.
You can also install packages privately, however, in your own home
directory.

Thus, reference to other manuals using '..' can't work in all cases in
an ordinary browser.  But they might work in enough cases to make this
a viable approach, provided we put all manuals in one directory.

Meanwhile, browsers specifically for HTML-Info could search the appropriate
list of directories in the cases where that is appropriate.

So I guess this sort of reference is sufficient.

Thanks.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Stefan Monnier wrote:
> Hey, I think this is a great idea: replace the "(emacs)Title"
> syntax with a URL.  When passed to Info, these URL would be redirected
> to the local Info pages.
>
> The main downside is that those URLs would take up more space.  But the
> upside is not just greater exposure of our HTML manuals to search
> engines, but also the removal of the ad-hoc (info "(emacs)Title") syntax.

Don't overlook two important parts of this: using the same name both for user input and for display, and using different names for different formats of a page (Info vs. HTML).

Web browsers have some useful navagation features:
0. An address bar, which shows the name of the currently displayed page.
1. A drop-down menu that shows the sequence of visited pages for the current buffer, and the current position within that sequence.
2. In the address bar, you can enter a new name and press enter to open that page.
3. The name shown is the same string as the string you enter to open the page by name.
4. You can copy the name that's shown.
5 Because of the preceding three features, you can save the name into a text file that you use as a list of bookmarks, paste the name back into the address bar to return to the page, and use the name to cite the page so your readers can open it; IOW, you can use the name to link to the page.
6. The name can include a hash mark and section name at the end, so that when you open the page, the browser jumps to the named section.

Emacs's Info browser has feature #0, but lacks the rest. Emacs's Info-history command partially provides #1, but doesn't show the actual link sequence that's traversed by Info-history-back and Info-history-forward. Instead of #2, Emacs makes you remember a command («g», for Info-goto-node) for entering the name of the page to open. Regarding #3, for example, I'm currently viewing the page with the shown name ⌜(elisp)Top > Keymaps > Translation Keymaps⌝[0], but that's effectively like an HTML page title; it isn't the name used for opening the page.

([0]: I actually had to manually transcribe that name, because incredibly, Emacs lacks feature #4. See bug #19471.)

Features #1 and #2 would be nice to have but aren't essential, #4 is essential but fortunately is easy to implement, and #6 is unnecessary if pages aren't too long. But the lack of #3, and consequently of #5, is the major problem. If you adopt URL syntax for page names, be sure to not only use it for Info-goto-node, but also display it in the address bar in the Info browser, e.g. ⌜http://gnu.org/emacs/24.4/docs/elisp/keymaps/translation_keymaps⌝, regardless of whatever other syntax (e.g. ⌜(elisp)Translation Keymaps⌝ as the short name) might also be usable to open the page. For #2, have the address bar be editable, and have Info-goto-node simply move focus to it.

There was a proposal somewhere in this ginormous thread to use the same name for both an Info page and an HTML page, and serve the Info page from the local cache but the HTML page via HTTP from the official server. That's a bad idea, because then the name's scope isn't global; instead, what the name resolves to depends on which system (local or remote-official) is queried.

If you try to fix that by relying on the User-agent or some other request header to choose which format to return, and having Emacs cache and use the format returned by sending ⌜Info⌝ for that header and having web browsers use the format returned by sending any other value for that header, then the URL is no longer the name of the page; instead, the URL+header is the name, which is a facepalm-inducing convention that's already a widespread plague that Emacs shouldn't exacerbate, akin to using URL+source-ip for page names in order to balkanize the web (conspicuous offenders include Google and CloudFlare).

You could instead conflate the protocol name and the page type name and say ⌜info:gnu.org/emacs/24.4/docs/elisp/keymaps/translation_keymaps⌝ if you want. That would still enable feature #3. Or instead append a ⌜.info⌝ extension to the end of the name, like is commonly done with HTML, though that could be misleading if the page doesn't have its own dedicated Info file. Both of these require you to replace the ⌜info⌝ in the name by ⌜http⌝ or ⌜html⌝ before sending the name to non-Emacs users.

I propose a cleaner solution: have the name with no type extension resolve to a redirect. Do client-side redirect, not server-side: serve a consistent response to all clients (regardless of request headers), containing both a standard HTTP redirect that web browsers will follow, and a new Info-file header that Info browsers will follow (web browsers will ignore it). The former points to a page with the same name but with ⌜.html⌝ appended, and the latter to the Info file that contains the requested Info page. This way, the extensionless URL is effectively the name of a directory from which browsers automatically choose one of two files, but the URL alone, not the URL plus a header, is the name of the directory, and the files have their own URLs.

When you receive page URLs from non-Emacs users, it's easy enough to chop off the ⌜.html⌝ extension. When you send them page URLs without the extension, their browsers will automatically redirect.

For example, if your browser (web or Info) sends this query for a documentation page:
GET /emacs/24.4/docs/elisp/keymaps/translation_keymaps HTTP/1.0
Host: gnu.org

then the response is:
HTTP/1.0 302 Found
Location: http://gnu.org/emacs/24.4/docs/elisp/keymaps/translation_keymaps.html
Info-file: http://gnu.org/emacs/24.4/docs/elisp.info

Web browsers will redirect to the URL in the Location header.
Info browsers will:
Fetch the file named in the Info-file header.
Chop the ⌜.info⌝ extension from the value of the Info-file header to get Info-base.
Chop Info-base from the front of the original page URL to get the name of the page (⌜/keymaps/translation_keymaps⌝ in this case) within the Info file.
Load that page from the file.
In the address bar, display the original page URL.

Info can send all web requests through a cache. Distribute Emacs with the cache preloaded with Info files, including the original URL for each of those files.
When Info queries the cache for a cached Info file, the cache returns a file descriptor for that file.
When Info queries for a noncached Info file, the cache downloads and caches it and returns a descriptor.
When Info queries for for any URL that starts with a string matching the URL of a cached Info file (excluding the ⌜.info⌝ extension), and the query URL itself doesn't have a filename extension, the cache generates and returns ⌜Info-file: X⌝ where X is the URL of the Info file. Info then processes this as a redirect.
When Info queries for anything else, the cache sends the query to the named server and returns the response to Info. If the response is a redirect, Info processes it.

This way, no network traffic is necessary for cached files. This also lets the same cache serve web browsers, not just Info browsers. The cache could be preloaded with HTML files for people who really don't like Info, and both Info and HTML files for people who like both. The cache doesn't need to be a server; it can just be a library, like sqlite is, and integrated into Emacs if only Info and Eww use it.

Indirecting through the Info-file header enables splitting or combining Info files without affecting the page URLs. E.g. elisp.info could be split up so that «keymaps», etc are in separate files, or elisp.info, emacs.info, and all the other Info files could be combined into one big docs.info file, but with either of those changes, the page URLs would remain unchanged.

It doesn't matter whether URLs are used in Info files (or in Texinfo files), or the Info browser just translates the names for input and display. What matters for users is just the Info browser's UI. But if Info files use only relative names, then the browser must know the original URL of the file in order to construct the URL for each page and show that name in the address bar. Therefore, the browser can't just search a path on the local system to find Info files, like it currently does when the user runs e.g. ⌜(info "(elisp)")⌝, unless the file format is changed to include its own URL. Alternatively, and more cleanly, the browser could just query the cache and have the cache do the search, and the cache can return ⌜Info-file: X⌝ if it finds a match, which Info then processes as a redirect.

For any query without a version number embedded in the name, the server should respond with a redirect to the same name but with the latest version number embedded. This makes it easy to check for updates, and to link to the always-latest version of a page.

For non-English manuals, there's no need to embed the language name in the URL; just use the source-ip address of the request to choose which version to serve, like Google does. (Just checking if anybody is still awake.)

RE: Correspondence between web-pages and Info-pages

[Drew Adams]

> 1. A drop-down menu that shows the sequence of visited pages for the
>    current buffer, and the current position within that sequence.
...
> Emacs's Info browser has feature #0, but lacks the rest. Emacs's
> Info-history command partially provides #1, but doesn't show the
> actual link sequence that's traversed by Info-history-back and Info-
> history-forward.

Scanned your mail quickly - just a quick response to #1: `L'.

Re: Correspondence between web-pages and Info-pages

[Eli Zaretskii]

> From: "Kelly Dean" <kelly@prtime.org>
> Date: Tue, 30 Dec 2014 11:17:45 +0000
> Cc: emacs-devel@gnu.org
> 
> Web browsers have some useful navagation features:
> 0. An address bar, which shows the name of the currently displayed page.
> 1. A drop-down menu that shows the sequence of visited pages for the current 
> buffer, and the current position within that sequence.
> 2. In the address bar, you can enter a new name and press enter to open that 
> page.
> 3. The name shown is the same string as the string you enter to open the page 
> by name.
> 4. You can copy the name that's shown.
> 5 Because of the preceding three features, you can save the name into a text 
> file that you use as a list of bookmarks, paste the name back into the address 
> bar to return to the page, and use the name to cite the page so your readers 
> can open it; IOW, you can use the name to link to the page.
> 6. The name can include a hash mark and section name at the end, so that when 
> you open the page, the browser jumps to the named section.

> Emacs's Info browser has feature #0, but lacks the rest.

Not really, see below (and your own conclusions are different as well).

> Emacs's Info-history 
> command partially provides #1, but doesn't show the actual link sequence that's 
> traversed by Info-history-back and Info-history-forward.

This doesn't sound like "Emacs lacks" the feature.  It's not even
partial.  It is just different from what you'd like it to be.

> Instead of #2, Emacs 
> makes you remember a command («g», for Info-goto-node) for entering the name of 
> the page to open.

You can use the menu bar if you don't remember the command.

> Regarding #3, for example, I'm currently viewing the page 
> with the shown name ⌜(elisp)Top > Keymaps > Translation Keymaps⌝[0], but that's 
> effectively like an HTML page title; it isn't the name used for opening the 
> page.

You can disable the "breadcrumbs" display by toggling an option, if
you don't like it.  But note that they are clickable, so they provide
yet another navigation aid, one that Web browsers generally lack.

> ([0]: I actually had to manually transcribe that name, because incredibly, 
> Emacs lacks feature #4. See bug #19471.)

Emacs doesn't lack that: you can copy the current node name to the
kill ring (and consequently to the clipboard) using the
Info-copy-current-node-name command.  This enables #5.

> For non-English manuals, there's no need to embed the language name in the URL; 
> just use the source-ip address of the request to choose which version to serve, 
> like Google does. (Just checking if anybody is still awake.)

YMMV, but I'm always tremendously annoyed by Google oh-so-helpful
decision what language I want to see my pages in.  I hope Emacs will
never follow that particular suit.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> Don't overlook two important parts of this: using the same name both for
> user input and for display,

That's good, yes, but is a UI issue which can be fixed regardless of
Info-vs-HTML-vs-whateverelse and regardless of which kind of names
we use.

IOW it's unrelated to the discussion at hand.
You can just `M-x report-emacs-bug' and you/we can fix those issues.

> and using different names for different formats
> of a page (Info vs. HTML).

No: I specifically don't want to use different names for different formats.
Instead I want to use a single name that works both in your web-browser
and in Emacs, and that gives the best experience possible in both cases
(i.e. in a web-browser it needs to be HTML, and inside Emacs it would
have to be Info for now and maybe some HTML-Info in some future).


        Stefan

RE: Correspondence between web-pages and Info-pages

[Kelly Dean]

Drew Adams wrote:
>> 1. A drop-down menu that shows the sequence of visited pages for the
>>    current buffer, and the current position within that sequence.
>...
>> Emacs's Info browser has feature #0, but lacks the rest. Emacs's
>> Info-history command partially provides #1, but doesn't show the
>> actual link sequence that's traversed by Info-history-back and Info-
>> history-forward.
>
> Scanned your mail quickly - just a quick response to #1: `L'.

L runs Info-history, which I addressed in my original message. You even quoted that part of my message.

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Eli Zaretskii wrote:
> Emacs doesn't lack that: you can copy the current node name to the
> kill ring (and consequently to the clipboard) using the
> Info-copy-current-node-name command.  This enables #5.

Thanks; I didn't know that. But it's still not user-friendly for a text editor to copy the wrong text using the standard copy command, and require use of a separate command to copy the right text. Whatever the reason is for the different internal behavior, it isn't something that users should have to care about or trip over.

> YMMV, but I'm always tremendously annoyed by Google oh-so-helpful
> decision what language I want to see my pages in.  I hope Emacs will
> never follow that particular suit.

I agree! Earlier in my original message, I strongly criticized Google for this, so I thought it would be obvious that my later suggestion to use source-ip was a joke, but just to be sure, I wrote ⌜Just checking if anybody is still awake.⌝

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Stefan Monnier wrote:
>> Don't overlook two important parts of this: using the same name both for
>> user input and for display,
>
> That's good, yes, but is a UI issue which can be fixed regardless of
> Info-vs-HTML-vs-whateverelse and regardless of which kind of names
> we use.
>
> IOW it's unrelated to the discussion at hand.

But I wasn't responding to the main discussion (of whether to replace Info). I just responded to the side discussion (for which you created a new subject line) of the names/syntax used for the UI for Info.

>> and using different names for different formats
>> of a page (Info vs. HTML).
>
> No: I specifically don't want to use different names for different formats.
> Instead I want to use a single name that works both in your web-browser
> and in Emacs, and that gives the best experience possible in both cases
> (i.e. in a web-browser it needs to be HTML, and inside Emacs it would
> have to be Info for now and maybe some HTML-Info in some future).

But in my original message, I proposed a solution that provides exactly what you're asking for (a single name that works in both web browsers and Info browsers), by using redirects to the HTML or Info page (each of which has its own name). I explained how it would work, and I think it covers all the issues raised in this subthread about how these names should work.

Re: Correspondence between web-pages and Info-pages

[chad]

> On 31 Dec 2014, at 20:24, Kelly Dean <kelly@prtime.org> wrote:
> 
>>> and using different names for different formats
>>> of a page (Info vs. HTML).
>> 
>> No: I specifically don't want to use different names for different formats.
>> Instead I want to use a single name that works both in your web-browser
>> and in Emacs, and that gives the best experience possible in both cases
>> (i.e. in a web-browser it needs to be HTML, and inside Emacs it would
>> have to be Info for now and maybe some HTML-Info in some future).
> 
> But in my original message, I proposed a solution that provides exactly what you're asking for (a single name that works in both web browsers and Info browsers), by using redirects to the HTML or Info page (each of which has its own name). I explained how it would work, and I think it covers all the issues raised in this subthread about how these names should work.

Redirects of this sort wont do what Stefan wants, because once youre
looking at one of the target destinations, the links youll have in
it will be to the post-redirected sources, which breaks on reference.
Put another way, after I go through the redirect, I cant cut-and-paste
the URL from the web browser and have it DTRT.

~Chad

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

chad wrote:
> Redirects of this sort wont do what Stefan wants, because once youre
> looking at one of the target destinations, the links youll have in
> it will be to the post-redirected sources, which breaks on reference.
> Put another way, after I go through the redirect, I cant cut-and-paste
> the URL from the web browser and have it DTRT.

But in the solution I proposed, the only change necessary to convert a post-redirect link to a pre-redirect link is (in the case of HTML as the redirect target) chop off the ⌜.html⌝ extension of the name. That's hardly a dealbreaker (and the Info browser can offer to chop it automatically if you feed it a URL with a ⌜.html⌝ extension). And even that's necessary only because web browsers traditionally discard the pre-redirect name. As I proposed for Info browsers, the name isn't discarded; what's shown in the address bar is the pre-redirect name, so no conversion is necessary.

Re: Correspondence between web-pages and Info-pages

[chad]

> On 01 Jan 2015, at 02:38, Kelly Dean <kelly@prtime.org> wrote:
> 
> chad wrote:
>> Redirects of this sort wont do what Stefan wants, because once youre
>> looking at one of the target destinations, the links youll have in
>> it will be to the post-redirected sources, which breaks on reference.
>> Put another way, after I go through the redirect, I cant cut-and-paste
>> the URL from the web browser and have it DTRT.
> 
> But in the solution I proposed, the only change necessary to convert a post-redirect link to a pre-redirect link is (in the case of HTML as the redirect target) chop off the ⌜.html⌝ extension of the name. That's hardly a dealbreaker (and the Info browser can offer to chop it automatically if you feed it a URL with a ⌜.html⌝ extension). And even that's necessary only because web browsers traditionally discard the pre-redirect name.

It’s not “tradition", it’s the behavior explicitly required by the spec.

If the info browser is re-parsing the URL anyway, whats the value
added by forcing any change into the web server at all?

~Chad

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

chad wrote:
> If the info browser is re-parsing the URL anyway, whats the value
> added by forcing any change into the web server at all?

Suppose Emacs gets an integrated browser, that displays both HTML pages and Info pages. Like Firefox is an integrated browser for HTML and PDF. In the latter case, if some document is available in both versions, you can often pick which one you want by just swapping ⌜.html⌝ vs. ⌜.pdf⌝ at the end of the URL. If both the HTML and PDF versions of a page were named ⌜foo⌝ (or even worse, both were named ⌜foo.html⌝), how would you pick which one to request from the server? Would you have the web browser send a different request header, so that the name of the PDF version is ⌜foo⌝ plus that header? That's the bad idea I argued against in my original message.

One of the desired features that other people have already expressed in this thread is for Info files to be available on the web, and enable the Info browser to automatically download files that it doesn't already have cached when you try to open URLs for Info pages that are in those files. So having a single name that resolves to an HTML page online in a web browser, but to an Info page offline in an Info browser, doesn't work. The Info browser has to work online, and it's logical to integrate it with the web browser, which means there must be a way to specify Info vs. HTML for the page you want. And you specify what you want by using the name of it. That name should be a URL, not a URL plus something else.

And the only change ‟forced into the web server” is to have the name ⌜foo⌝ resolve to a redirect page (which is already a standard feature available in web server software), so that names are just URLs, and clients, not servers, choose whether to redirect to foo.html (specified by the Location header, compatible with standard web browsers) or to the Info file specified by the Info-file header (which Emacs's Info browser will understand). An HTML-Info-integrated browser in Emacs will understand both, so it can offer the user a choice. If you prefer Info, and people send you post-redirect names to HTML, you can tell Info to automatically chop off the ⌜.html⌝ extension. If you prefer HTML, no change is necessary. When you send people names, you or they can chop off the ⌜.html⌝. The name with no extension is simply a way to automatically give people a link to both formats of the page, not just to one or the other.

The value added is:
There's a single name that points to both the Info and HTML pages, as Stefan wants.
The choice is made by the client, as explained above and in my original message.
The design enables clean integration of the HTML browser and the Info browser in the future.

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Suppose Emacs gets an integrated browser, that displays both HTML
  > pages and Info pages. Like Firefox is an integrated browser for
  > HTML and PDF. In the latter case, if some document is available in
  > both versions, you can often pick which one you want by just
  > swapping  .html  vs.  .pdf  at the end of the URL. If both the
  > HTML and PDF versions of a page were named  foo  (or even worse,
  > both were named  foo.html ), how would you pick which one to
  > request from the server?

Does this problem need to be solved?

I want to replace current Info format with an HTML-Info format that
will be valid HTML, used in a stylized way.  This Emacs browser (like
any other browser) will always get our manuals in the form of HTML.
It won't need to try to handle some other format.

If the browser is Info-aware, it will determine from the contents of
the manual whether to implement the Info commands on it.

There will be no need for browsers to try to choose between two
formats of a manual, if the only format we use is a form of HTML.
Rather, the two modes we will want a browser to handle are (1) locally
installed files and (2) files fetched with http over the web.
Since the same files could be accessed either way, we want to make
sure that the same file contents work both ways.  This affects how
cross-refereces have to be handled.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

>> Suppose Emacs gets an integrated browser, that displays both HTML
>> pages and Info pages. Like Firefox is an integrated browser for
>> HTML and PDF. In the latter case, if some document is available in
>> both versions, you can often pick which one you want by just
>> swapping  .html  vs.  .pdf  at the end of the URL. If both the
>> HTML and PDF versions of a page were named  foo  (or even worse,
>> both were named  foo.html ), how would you pick which one to
>> request from the server?

> Does this problem need to be solved?

No it doesn't.  And the reason has nothing to do with the format.
The reason is that we just want to define URLs which are 100% equivalent
in meaning to "(<FILE>)<NODE>".  The format associated is
100% unrelated.

I repeat: this discussion of using URL names for manual node references
has nothing to do with the format of those manuals.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Richard Stallman wrote:
> There will be no need for browsers to try to choose between two
> formats of a manual, if the only format we use is a form of HTML.

That's true. I thought the consensus was to continue supporting the Info format for the time being, add URL syntax to the Info browser, and dump the Info format (and standard HTML, as currently used for manual pages on gnu.org) only after a new format was ready to replace it. That would mean there would be a period when URLs were used for two formats (Info and HTML), so I proposed a way to handle that. But if URL syntax isn't going to be introduced for the Info browser until the new format is ready to replace both Info and the currently-used form of HTML, then my proposal to use redirection to handle both isn't necessary.

> Rather, the two modes we will want a browser to handle are (1) locally
> installed files and (2) files fetched with http over the web.
> Since the same files could be accessed either way, we want to make
> sure that the same file contents work both ways.  This affects how
> cross-refereces have to be handled.

The solution to that, of course, is to simply have the browser fetch through a cache, like standard web browsers do. To ‟install” files locally, just fetch them, then pin them in the cache. Emacs releases can come with the appropriate files preloaded (and pinned) in the cache, so no network connection is needed to browse those files. To uninstall files, just purge them from the cache, or just un-pin them and let them be automatically purged to make room for new data.

For intra-domain cross-references (even inter-manual, so long as intra-domain), use relative links, which is standard practice on the web. Web browsers automatically convert relative links to absolute (based on the absolute URL that was used to fetch the page (and this URL is recorded in the cache along with the page itself)), so relative links are never exposed to users except when they look at a page's source code. The only time you need absolute links in your manuals is for inter-domain cross-references.

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Stefan Monnier wrote:
>> Does this problem need to be solved?
>
> No it doesn't.

You're right, assuming only one format will be used, and apparently that's the consensus.

> And the reason has nothing to do with the format.

True. But my proposal to use redirection to handle multiple formats had nothing to do with the format, but only with the _quantity_ of formats for which URL syntax would be used. I thought that quantity would be two, but the consensus appears to be one. My proposal for redirection is only useful if the quantity is greater than one.

My proposal _also_ happened to include a way to specify the Info file that contains a page, to handle the usual case of multiple Info pages per file (unlike for HTML, which normally has each page in a separate file), because I assumed that Info would be one of the formats used, but that's a separate issue from using redirection to handle multiple formats.

> we just want to define URLs which are 100% equivalent
> in meaning to "(<FILE>)<NODE>".  The format associated is
> 100% unrelated.
>
> I repeat: this discussion of using URL names for manual node references
> has nothing to do with the format of those manuals.

Agreed.

Re: Correspondence between web-pages and Info-pages

[Nic Ferrier]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I repeat: this discussion of using URL names for manual node references
> has nothing to do with the format of those manuals.

I agree.


Nic

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > That's true. I thought the consensus was to continue supporting
  > the Info format for the time being, add URL syntax to the Info
  > browser, and dump the Info format (and standard HTML, as currently
  > used for manual pages on gnu.org) only after a new format was
  > ready to replace it.

I wouldn't ask people to do that much extra work for this transition.
There are easier ways to handle it.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The solution to that, of course, is to simply have the browser
  > fetch through a cache, like standard web browsers do. To  install 
  > files locally, just fetch them, then pin them in the cache.

The manuals should be included in our packages and installed
just as they are now.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> True. But my proposal to use redirection to handle multiple formats had
> nothing to do with the format, but only with the _quantity_ of formats for
> which URL syntax would be used.

I don't think there's any current problem to solve in this area.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Richard Stallman wrote:
>> The solution to that, of course, is to simply have the browser
>> fetch through a cache, like standard web browsers do. To  install
>> files locally, just fetch them, then pin them in the cache.
>
> The manuals should be included in our packages and installed
> just as they are now.

What's the advantage?

If the Info browser (or HTML-Info browser or whatever) is going to support reading manuals online that the user doesn't already have a local copy of, which is a feature that other people in this thread have already said would be a good idea, then in practice, the browser is going to need a cache, for the same reason that standard web browsers have caches.

Using a cache, of course, means the browser will support looking in a local place (the cache) for manuals that the user tries to read, and if they're there, display them with no network traffic required. Since that cache will be needed anyway, I proposed to use it as the place to put the manuals that come with Emacs.

So when you rebut my proposal and say, ‟The manuals should be included in our packages and installed just as they are now”, it seems you're saying the manuals should be put in a different place P than the browser's cache C. What happens when the user enters the URL of a manual page? Local and online copies of the content are identical (since the version number will be encoded in the URL), so of course, the browser should check P, and if the content is there, not bother checking online.

But the browser also checks C. Since that's the case, what's the advantage of having P and C be different? They should be the same, for simplicity's sake. IOW, put the manuals in the cache (preload them there in Emacs releases), and pin them there by default.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> What's the advantage?

I don't understand this discussion because it seems it's not talking
about the same thing as that for which I started this thread with its
new "Subject:".

To get us back on track: I'm proposing (and hoping someone can help
implement) a change in the format of references from "(<file>)<node>" to
some other format that would also happen to be a URL that random
browsers can use.  The new URL format would probably look like
<prefix><file><separator><node><suffix> where <prefix>, <separator>,
and <suffix> would be constants.

I can imagine accepting a few different <prefix>es, which would be
listed in some Info-url-prefixes variable, for the benefit of Info
manuals not available on a gnu.org machine since the default/main prefix
would probably look like "http://www.gnu.org/...".

Tho maybe we could instead simply accept "any" <prefix>, as long as
<file><separator><node><suffix> can be extracted reliably from the URL.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Nic Ferrier]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> What's the advantage?
>
> I don't understand this discussion because it seems it's not talking
> about the same thing as that for which I started this thread with its
> new "Subject:".
>
> To get us back on track: I'm proposing (and hoping someone can help
> implement) a change in the format of references from "(<file>)<node>" to
> some other format that would also happen to be a URL that random
> browsers can use.  The new URL format would probably look like
> <prefix><file><separator><node><suffix> where <prefix>, <separator>,
> and <suffix> would be constants.
>
> I can imagine accepting a few different <prefix>es, which would be
> listed in some Info-url-prefixes variable, for the benefit of Info
> manuals not available on a gnu.org machine since the default/main prefix
> would probably look like "http://www.gnu.org/...".
>
> Tho maybe we could instead simply accept "any" <prefix>, as long as
> <file><separator><node><suffix> can be extracted reliably from the
> URL.

I will try and solve this in the new info viewer.

Other than that I don't think there's any point.


Nic

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The idea of local installation of manuals is that installing a package
installs its manuals permanently.

A cache is transitory, and it would be hard for package installation
to put manuals there.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   The new URL format would probably look like
  > <prefix><file><separator><node><suffix> where <prefix>, <separator>,
  > and <suffix> would be constants.

I think it has been worked out that <prefix> should be '../'.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

>> The new URL format would probably look like
>> <prefix><file><separator><node><suffix> where <prefix>, <separator>,
>> and <suffix> would be constants.

> I think it has been worked out that <prefix> should be '../'.

No, you can't just pass "../emacs/Top" to your browser and expect it to
figure out that the manual is on www.gnu.org.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Richard Stallman wrote:
> The idea of local installation of manuals is that installing a package
> installs its manuals permanently.
>
> A cache is transitory

That's why I wrote ⌜pin them there⌝.

> and it would be hard for package installation
> to put manuals there.

Using HTTP (not HTTPS) in your web browser, open one of the pages of the HTML versions of manuals on gnu.org. There, your browser just installed a local copy of that page, completely automatically. That's not hard.

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > No, you can't just pass "../emacs/Top" to your browser and expect it to
  > figure out that the manual is on www.gnu.org.

Aren't we talking about links in other Info manuals?  In that context,
yes it should work.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > and it would be hard for package installation
  > > to put manuals there.

  > Using HTTP (not HTTPS) in your web browser, open one of the pages
  > of the HTML versions of manuals on gnu.org. There, your browser
  > just installed a local copy of that page, completely
  > automatically. That's not hard.

It is not onerous work, but it requires users to actively do
something.  That is a change for the worse, so I don't want it.  I
want package installation to install the package's info manuals
locally, just as it does now.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> Aren't we talking about links in other Info manuals?

No, I'm talking about the general case of a reference which can appear
cross-manuals, or in email messages, or in web-pages, or in a bookmark, ...


        Stefan

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Aren't we talking about links in other Info manuals?

  > No, I'm talking about the general case of a reference which can appear
  > cross-manuals,

That's the case I was discussing, and ../ should work there.

		   or in email messages, or in web-pages, or in a bookmark, ...

Up till now, we have no way to write a link to an Info manual
in such contexts.  The only place we support them is in other Info files.

So you're proposing a new feature.  I agree it would be nice to have.
My point is that anything along these lines will be a step up from
what we have now, so we need not be perfectionist about it.
Whatever is easy to do will be an advance.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> 		   or in email messages, or in web-pages, or in a bookmark, ...
> Up till now, we have no way to write a link to an Info manual
> in such contexts.

Actually, we kind of do with a syntax like (info "(<FILE>)<NODE>"),
which is recognized at least in docstrings and is used in email messages.

> My point is that anything along these lines will be a step up from
> what we have now, so we need not be perfectionist about it.
> Whatever is easy to do will be an advance.

Right.  But it impacts the current in-manual (and cross-manual) syntax
in favor of the new syntax, so it does require some care.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Actually, we kind of do with a syntax like (info "(<FILE>)<NODE>"),
  > which is recognized at least in docstrings and is used in email messages.

That's a Lisp expression.  I see that as a different category of thing.

It will still work, with HTML-Info.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Correspondence between web-pages and Info-pages

[Stefan Monnier]

> It will still work, with HTML-Info.

Of course, as I said, this is completely unrelated to the format of the
manual nodes.


        Stefan

Re: Correspondence between web-pages and Info-pages

[Kelly Dean]

Richard Stallman wrote:
> It is not onerous work, but it requires users to actively do
> something.  That is a change for the worse, so I don't want it.  I
> want package installation to install the package's info manuals
> locally, just as it does now.

That's why I wrote in my very first message in this thread:
⌜Distribute Emacs with the cache preloaded with Info files⌝

And later, in a reply to you:
⌜Emacs releases can come with the appropriate files preloaded (and pinned) in the cache⌝

And in yet a later reply to you, after you replied to the previous one:
⌜put the manuals in the cache (preload them there in Emacs releases), and pin them there⌝

IOW, users don't have to do anything. The manuals come preloaded. When you download Emacs, the manuals come with it, just like they do now. When you download a package that has a manual, it can put the manual in the same place where Emacs's manuals are: the cache. And pin it there.

And so we don't go in circles anymore, I'll again quote a reply I wrote to you:
⌜you're saying the manuals should be put in a different place P than the browser's cache C. ... what's the advantage of having P and C be different?⌝

Re: Correspondence between web-pages and Info-pages

[Ivan Shmakov]

>>>>> Kelly Dean <kelly@prtime.org> writes:

[…]

 > And so we don’t go in circles anymore, I’ll again quote a reply I
 > wrote to you: ⌜you’re saying the manuals should be put in a different
 > place P than the browser’s cache C.  … what’s the advantage of
 > having P and C be different?⌝

	I guess that’s because each and every browser (or at least
	engine) follows its own way when accessing and maintaining the
	cache.

	To the best of my knowledge, there’s nothing like a per-user
	~/.browser-cache or system-wide /var/cache/browser directory
	where the software’s installation procedure could install
	anything so that that would be deemed “cached” by just any
	browser available in the system.

	Which is contrary to, say, /usr/share/info.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A