bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'

[Vincent Belaïche]

----------------------------------------
> Date: Fri, 22 Aug 2014 23:57:13 +0300
> From: eliz@gnu.org
> Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for 
> '(texinfo) @- @hyphenation'
> To: gavinsmith0123@gmail.com
> CC: rms@gnu.org; Vincent.b.1@hotmail.fr; 18308@debbugs.gnu.org
>
> > Date: Fri, 22 Aug 2014 21:12:06 +0100
> > From: Gavin Smith <gavinsmith0123@gmail.com>
> > Cc: Eli Zaretskii <eliz@gnu.org>, Vincent Belaïche <Vincent.b.1@hotmail.fr>,
> > 18308@debbugs.gnu.org
> >
> > On Fri, Aug 22, 2014 at 6:17 PM, Richard Stallman <rms@gnu.org> wrote:
> > > I think the real fix for this sort of thing is to develop
> > > a replacement for the Info reader which uses HTML.
> > > That's why I was enthusiastic about that project when it was announced.
> >
> > Somebody would have to define how HTML should be used for Texinfo manuals, 
> > e.g.:
> > * Naming of HTML files for references between nodes and files
> > * How indices should be expressed
> > * What version of HTML, what constructs are allowed.
> > * Where these files are to be stored in the filesystem
>
> More importantly: how will I use index-search in an HTML browser.

Sorry for the naive comment: Texinfo can already be compiled to HTML
(and docbook and quite a few other things) 

For instance the manuals of jPicEdt have been ported to Texinfo (I have
even made some html to texinfo converter for that) and they can be
viewed from jPicEdt by some simple java HMTL viewer.

So already nothing prevents people to compile all the EMACS manuals to
HMTL and browse them with their favorite navigator.

Maybe you mean that the HTML viewer has to be embedded into EMACS. What
would then be the difference if all the documentation is compiled to
HTML and you get it with having, say w3m installed along with EMACS, and
call emacs-w3m from C-h i, or any such text oriented web browser for
EMACS (http://www.emacswiki.org/emacs/w3).


Anyway, I think that you need to keep the old info viewer inside EMACS
because people --- at least me --- have plenty of info files not related
to EMACS in several locations on their hard drive and they like to use
EMACS as a viewer --- because EMACS is already running ;-) --- and you
may also have info links in org pages and so on --- or some info manuals
making some external reference to some node in some other manuals,
etc...

To me the main advantage of info format is that
* it loads in no time (text oriented), 
* navigation is made faster for all the shortcuts
* easier to search the manual 

BTW --- don't take me wrong, this is not a provocation, nor a joke ---
if the point is to go HTML, why not rather use some sort of compressed
HTML like the microsoft CHM format. Maybe even this format is open and
free and could be used as is. HTML is rather verbous..., but anyway help
files are not such a big amount of data and text files are easier to
handle in many aspects.

Personally I think that one should first think about what sort of
advantage you are seeking with going HTML for helpfiles, what is the
real motivation:

* add some interactivity (javascript, etc...)
* render MathML for math or SVG for picture
* make fancier look-and-feel
* other ...

Finally, as an EMACS user, it would be more important to me

* if docstring could be written in a sort of texinfo-light format (when
  you create a package or anything you first do docstring, and then you
  port this to a manual (so having some texinfo-light format from the
  beginning would reduce the effort)

* if docstring could be localized (texinfo allows that, like the
  manuals, after all, but the current docstring format sort of force you
  into English as the text is interpreted)

* if you could use within the docstring some pointer to some definition
  in the manual and withdraw this part only --- this is not just a
  matter of disk space:
  * duplication of information is simply evil
  * to that extent, some package like calc don't have docstrings for
    math library function because only the manual is maintained, after
    all why should Jay bother doing the job twice.
  * that would also make it easier to change the doc language by just
    switching the locale if one maintain parallel doc tree for each
    language, and resolve the manual address by falling back to default
    language doc tree when the manual does not exists in the locale doc
    tree

Concerning the info format, what sort of problem I also see --- still in
relation to i18n --- is that one should be able to use exactly the same
node names whatever the language, so that the same link can be used, and
when the manual is compiled to multifile HTML, you have the same file
tree whatever the language. I think that this would also make easier the
translation process because it would be easier to relate manuals in two
different languages. What I am meaning is that using the same node names
should not imply that when the final user is reading a manual written in
non-English he/she has to see the real node names unless he/she copy to
clipboard the node address, one should be able to specify along with the
node name a node local name to be presented by the viewer (menu labels
could be used for that for nodes that are referred from a menu, but
there could also be some specific texinfo command, and something
explicit in the info file also). There should also be more freedom for
characters usable in the "node local name" as it is intended for the
final user --- no problem if there are forbidden characters in the node
name, as long as it is overlayable by the local name in the user's view.

  Vincent.