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

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

[Vincent Belaïche]

In texinfo manual, info node `(texinfo) Breaks', if I set pointer on
third menu entry and type RET, the I get message:

user-error: No such node or anchor: @-  @hyphenation

However, if I type '3', then I go to the wanted node.

VBR,
   Vincent Belaïche.

PS: I have not tried it with emacs -Q, I think that it won't make a
difference, please make me know if needed.
-----------------------------------------------------------------------


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-07-20 on CHOUNEK
Repository revision: 117552 monnier@iro.umontreal.ca-20140719165640-ydu9k3ol9e4syaxt
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --prefix=c:/Programme/GNU/Emacs --without-jpeg
 --without-tiff --without-gif --without-png 'CPPFLAGS= -DFOR_MSW=1 -I
 C:/Programme/GNU/installation/emacs-install/libXpm-3.5.8/include -I
 C:/Programme/GNU/installation/emacs-install/libXpm-3.5.8/src -L
 c:/Programme/GNU/installation/emacs-install/libXpm-3.5.8/src'
 CPP=/mingw/bin/cpp.exe
 PKG_CONFIG_PATH=/mingw/lib/pkgconfig:/usr/local/lib/pkgconfig'

Configured features:
XPM NOTIFY ACL ZLIB

Important settings:
  value of $EMACSPATH: c:\Programme\NGNU\CVS;C:\Programme\GNU\GnuPG;c:\Programme\apache-ant-1.8.0\bin;c:\msys\1.0\bin;c:\msys\1.0\mingw\bin;
  value of $LANG: FRA
  locale-coding-system: cp1252

Major mode: Info

Minor modes in effect:
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  recentf-mode: t
  mail-abbrevs-mode: t
  iswitchb-mode: t
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  line-number-mode: t

Recent input:
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> C-h i u 3 
u m C-g <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <right> <right> <right> 
<right> <return> u <down> <right> <return> <down> <return> 
u <down> <return> u <up> <up> <up> <down> <right> <right> 
<right> M-x r e p o r <tab> b u g <tab> <tab> i <tab> 
<backspace> <tab> <tab> e m <tab> <tab> <return> I 
n SPC f o <backspace> <backspace> <backspace> f o SPC 
w i v <backspace> <backspace> <backspace> v i e w e 
r SPC d o e s SPC n o t SPC f o l l o w SPC m e n u 
SPC e n t u <backspace> r y C-x o 3 w C-x b <return> 
C-g C-x b r e <backspace> <backspace> b u g C-g C-x 
4 b C-g C-x d C-g C-x C-g C-x b * b a <return> c d 
SPC . . / . . / <return> c x d <backspace> <backspace> 
d SPC t e x i n <tab> i n <tab> t e x <backspace> <backspace> 
<backspace> <return> C-x d <return> <down> <down> <down> 
<down> <down> C-x b <return> c d SPC t r u <tab> / 
d o <tab> <return> m a k e SPC t e x i n f o . i n 
f o <return> c p SPC t e x i n <tab> i n <tab> SPC 
/ s h a r e / i n f <tab> o <return> C-x b C-g C-h 
i C-x d C-g M-x r e v e r t - b u f <tab> <return> 
y u <right> <return> 3 w M-x <up> <up> <return>

Recent messages:
C-x C-g is undefined
c:/Programme/GNU/installation 
c:/Programme/GNU/installation/texinfo-install 
c:/Programme/GNU/installation/texinfo-install/trunk/doc 
No match
Quit [2 times]
Revert info buffer? (y or n) y
Reverted c:/msys/1.0/share/info/texinfo
user-error: No such node or anchor: @-  @hyphenation
(texinfo) @- @hyphenation

Load-path shadows:
d:/msys/1.0/home/Vincent/.emacs.d/etc/custom hides c:/Programme/GNU/Emacs/share/emacs/24.4.50/lisp/custom
c:/Programme/GNU/Emacs/share/emacs/24.4.50/lisp/loaddefs hides c:/Programme/GNU/installation/cedet-install/cedet/lisp/cedet/loaddefs

Features:
(shadow emacsbug make-mode org-clock reftex-sel reftex-ref reftex-toc
vc-arch vc-mtn vc-hg vc-bzr vc-sccs vc-rcs log-edit pcvs pcvs-parse
pcvs-info pcvs-defs pcvs-util ewoc calc-aent calc-yank balance picture
cal-move meta-mode diary-lib diary-loaddefs cal-iso org-element
org-rmail org-mhe org-irc org-info org-gnus org-docview doc-view
image-mode org-bibtex bibtex org-bbdb org-w3m org-agenda org org-macro
org-footnote org-pcomplete org-list org-faces org-entities org-version
ob-emacs-lisp ob ob-tangle org-src ob-ref ob-lob ob-table ob-keys ob-exp
ob-comint ob-core ob-eval org-compat org-macs org-loaddefs cal-menu
calendar cal-loaddefs reftex-parse bookmark nnir mule-util flow-fill ses
unsafep bat-mode jde-ant jde derived jde-annotations jde-open-source
semantic/senator jde-bsh jde-parse-expr jde-class jde-parse-class
jde-import jde-java-font-lock jde-which-method jde-java-grammar jde-wiz
jde-complete eldoc semantic/idle working fame jde-plugins executable
browse-url jde-gen tempo jde-run jde-jdb jde-bug jde-dbs jde-dbo regress
jde-db jde-parse sregex jde-imenu semantic/imenu imenu semantic/db-file
semantic/adebug eieio-datadebug data-debug cedet-files semantic/java
semantic/db-mode semantic/decorate/include semantic/db-find
semantic/db-ref semantic/db eieio-base semantic/decorate/mode
semantic/decorate pulse semantic/doc thingatpt avl-tree semantic/sb
semantic/sort semantic/format semantic/tag-ls semantic/find
semantic/ctxt jde-compile semantic/util-modes semantic/util semantic
semantic/tag semantic/lex semantic/fw mode-local jde-help jde-widgets
beanshell lmenu jde-custom jde-project-file jde-util arc-mode
archive-mode efc jde-autoload cedet calc-alg calc-menu calc-prog
calc-forms cus-edit vc-cvs cc-langs iso-transl jka-compr ispell quail
gnus-cite mm-archive gnus-async gnus-bcklg gnus-ml nndraft nnmh nndoc
nnfolder bbdb-gnus bbdb-mua gnus-agent gnus-srvr gnus-score score-mode
nnvirtual gnus-msg gnus-art mm-uu mml2015 epg-config mm-view mml-smime
smime dig nntp gnus-cache gnus-sum gnus-group gnus-undo gnus-start
gnus-cloud nnimap nnmail mail-source utf7 netrc nnoo parse-time
gnus-spec gnus-int gnus-range gnus-win gnus gnus-ems nnheader rect debug
warnings compile nxml-uchnm rng-xsd xsd-regexp rng-cmpct rng-nxml
rng-valid rng-loc rng-uri rng-parse nxml-parse rng-match rng-dt rng-util
rng-pttrn nxml-ns nxml-mode nxml-outln nxml-rap nxml-util nxml-glyph
nxml-enc xmltok network-stream starttls tls mailalias smtpmail
auth-source password-cache qp sort mail-extr bbdb-com two-column generic
mailcap etags bbdb-message sendmail gnus-util message format-spec rfc822
mml mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils gmm-utils mailheader
info dbus xml diff-mode vc ediff-vers ediff-merg ediff-wind ediff-diff
ediff-mult ediff-help ediff-init ediff-util ediff texmathp vc-dispatcher
vc-svn dired-aux vc-git add-log pcmpl-unix tex-info texinfo eieio-opt
speedbar sb-image ezimage dframe find-func misearch multi-isearch pp
help-mode preview prv-emacs reftex-dcr reftex-auc reftex reftex-vars
tex-bar tex-buf toolbar-x noutline outline font-latex latex easy-mmode
tex-style tex crm advice help-fns latexenc hl-line shell pcomplete
comint ansi-color ring dired-x dired accents-ascii eieio byte-opt
bytecomp byte-compile cconv eieio-core tex-mik preview-latex tex-site
auto-loads calc-mathfloat calc-math edmacro kmacro w32utils java-init
cl-macs cl gv bsh-init recentf tree-widget wid-edit cl-loaddefs cl-lib
generic-x cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align
cc-engine cc-vars cc-defs template mailabbrev iswitchb cus-start
cus-load bbdb easymenu bbdb-site timezone bbdb-loaddefs calc-misc
calc-arith calc-ext calc calc-loaddefs calc-macs skeleton
load-path-to-cedet-svn time-date tooltip electric uniquify ediff-hook
vc-hooks lisp-float-type mwheel dos-w32 ls-lisp w32-common-fns
disp-table w32-win w32-vars tool-bar dnd fontset image regexp-opt fringe
tabulated-list newcomment lisp-mode prog-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer nadvice loaddefs button
faces cus-face macroexp files text-properties overlay sha1 md5 base64
format env code-pages mule custom widget hashtable-print-readable
backquote make-network-process w32notify w32 multi-tty emacs)

Memory information:
((conses 8 1172934 201877)
 (symbols 24 76765 0)
 (miscs 20 1638 6998)
 (strings 16 192911 13666)
 (string-bytes 1 6458191)
 (vectors 8 77529)
 (vector-slots 4 2025283 89992)
 (floats 8 429 1535)
 (intervals 28 72652 4102)
 (buffers 508 137))

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

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr> 
> Date: Thu, 21 Aug 2014 10:45:11 +0200
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>
> 
> In texinfo manual, info node `(texinfo) Breaks', if I set pointer on
> third menu entry and type RET, the I get message:
> 
> user-error: No such node or anchor: @-  @hyphenation

This is not an Emacs bug, it's a bug in the Texinfo manual.  For some
reason, it sometimes refers to this node as "@-  @hyphenation" (with 2
spaces), and sometimes as "@- @hyphenation" (with only 1 space).  The
menu uses the former, while the node name uses the latter.  So Emacs
cannot find the node.

> However, if I type '3', then I go to the wanted node.

That's because the command bound to '3' normalizes the whitespace in
the node name.  I don't know why it does that, but that code exists
since about forever.

Maybe we could consider normalizing the whitespace in the 1st case as
well, but that's just a work around for a buggy manual.

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

[Vincent Belaïche]

Resent With cc to 18308@debbugs.gnu.org

Feedback inserted below...

----------------------------------------
> Date: Thu, 21 Aug 2014 17:12:13 +0300
> From: eliz@gnu.org
> Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
> To: vincent.b.1@hotmail.fr
> CC: 18308@debbugs.gnu.org
>
> > From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> > Date: Thu, 21 Aug 2014 10:45:11 +0200
> > Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>
> >
> > In texinfo manual, info node `(texinfo) Breaks', if I set pointer on
> > third menu entry and type RET, the I get message:
> >
> > user-error: No such node or anchor: @- @hyphenation
>
> This is not an Emacs bug, it's a bug in the Texinfo manual. For some
> reason, it sometimes refers to this node as "@- @hyphenation" (with 2
> spaces), and sometimes as "@- @hyphenation" (with only 1 space). The
> menu uses the former, while the node name uses the latter. So Emacs
> cannot find the node.
>
> > However, if I type '3', then I go to the wanted node.
>
> That's because the command bound to '3' normalizes the whitespace in
> the node name. I don't know why it does that, but that code exists
> since about forever.
>
> Maybe we could consider normalizing the whitespace in the 1st case as
> well, but that's just a work around for a buggy manual.


I would not say that this is a bug in the manual --- manuals are written
by human beings, and human beings are living creatures, just like bugs
are ;-) .

Rather, I think that this is a bug in the texinfo info compiler that
should:

1) produce some warning message, as a matter of fact the manual is not
   consistent with info node `(texinfo) Node Line Requirements' --- see
   below why

2) collapse multiple spaces to a single space in node names as the info
   file is produced.

In info node "(texinfo) Node Line Requirements", there is this
statement:


-----------------------------------------------------------------------
     Spaces before and after names on the '@node' line are ignored.
     Multiple whitespace characters "inside" a name are collapsed to a
     single space.  For example:

          @node  foo bar,
          @node foo bar ,
          @node foo  bar,
          @node  foo  bar ,

     all define the same node, namely 'foo bar'.  References to the node
     should all use that name, with no leading or trailing spaces a
     single internal space.
-----------------------------------------------------------------------

It seems that there is a typo in this node and the end of last sentence
should read: "with no leading or trailing spaces *AND* a single internal
space". Anyway, because the menu entry is a REFERENCE to the node, then
it should use this name with a single internal space. Because it does
not, the manual is not conformant to this spec.

So, I think that you treate the EMACS info viewer bug as you like ---
either close it, or think that you should make the info viewer more
robust by collapsing multiple internal spaces to a single space like the
'3' command does. My personal feeling is that you should robustify the
info viewer.

On my side I will open a bug Texinfo project to refer to this one and
ask for compiler to handle point 1) and 2) above and correct the typo in
the manual.

  Vincent.

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

[Vincent Belaïche]

Dear Eli et alii,

Looping also through Gavin.

For your information I have filed these two bugs to texinfo.

http://savannah.gnu.org/bugs/index.php?43045
http://savannah.gnu.org/bugs/index.php?43042

During the discussion on bug-texinfo@gnu.org concerning texinfo
bug#43042, I received the following comment from Gavin Smith:

> I don't think it is actually the case that references should use
> normalized whitespace. For example, there is the following in the bash
> manual, node "Shell Operation":
>
>   3. Parses the tokens into simple and compound commands (*note Shell
>      Commands::).
>
> Here we have a newline and initial line indent in the middle of the
> node name "Shell Commands", but following this cross-reference works
> fine.

I a nutshell, there are cases of node references where the info viewer
is not bothered by internal multiple spaces (this cross reference inside
bash manual), and other cases where the info viewer cannot handle it
(the case of node "(texinfo) @- @hyphenation" pointer in menu entry of
upper node).

So, on second thoughts, I am thinking in the end that for consistency,
the info viewer not only should, but also _must_ be corrected.

I am even speculating that in the case of the manual menu entry,
probably it was intentional to put more spaces for the entry to read
better (as @- and @hyphenation are two different commands, isn't it a
good idea to put a little more space between them).

Maybe the texinfo manual could also be corected as follows (with two
spaces in label, and one space in node pointer):

* @t{@@-  @@hyphenation}: @t{@@- @@hyphenation}.            Helping @TeX{} with hyphenation points.

ie by using the

* LABEL: NODE. TITLE

construct instead of the

* NODE:: TITLE

construct. Well... this is not your business, but if Gabin had read this
email up to this point, he may have an opinion.

VBR,
   Vincent.

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

[Eli Zaretskii]

> From: Vincent Belaïche <Vincent.b.1@hotmail.fr> 
> Cc:  18308@debbugs.gnu.org
> Date: Fri, 22 Aug 2014 00:23:44 +0200
> 
> During the discussion on bug-texinfo@gnu.org concerning texinfo
> bug#43042, I received the following comment from Gavin Smith:
> 
> > I don't think it is actually the case that references should use
> > normalized whitespace. For example, there is the following in the bash
> > manual, node "Shell Operation":
> >
> >   3. Parses the tokens into simple and compound commands (*note Shell
> >      Commands::).
> >
> > Here we have a newline and initial line indent in the middle of the
> > node name "Shell Commands", but following this cross-reference works
> > fine.
> 
> I a nutshell, there are cases of node references where the info viewer
> is not bothered by internal multiple spaces (this cross reference inside
> bash manual), and other cases where the info viewer cannot handle it
> (the case of node "(texinfo) @- @hyphenation" pointer in menu entry of
> upper node).

Emacs already does all that, of course.  Just not in the case of the
menu entries, where the node names are not expected to span more than
one line.

> So, on second thoughts, I am thinking in the end that for consistency,
> the info viewer not only should, but also _must_ be corrected.

As I said, maybe.  But the fact is that the _Texinfo_source_ of the
Texinfo manual uses different amounts of blanks in this node's name.
So line breaking and filling in the Info file is not the issue here.

> I am even speculating that in the case of the manual menu entry,
> probably it was intentional to put more spaces for the entry to read
> better (as @- and @hyphenation are two different commands, isn't it a
> good idea to put a little more space between them).

The problem is _inconsistency_, not extra blanks.  The number of
blanks should have been consistent in all the uses of this node name.

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

[Vincent Belaïche]

Hello Eli, Gavin, Patice, & Karl.

Looping also through Patrice Dumas and Karl Berry and texinfo-bug
list.

Useful links:

http://savannah.gnu.org/bugs/?43045
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18308

Answers & comments below:

----------------------------------------
> Date: Fri, 22 Aug 2014 09:36:14 +0300
> From: eliz@gnu.org
> Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
> To: Vincent.b.1@hotmail.fr
> CC: gavinsmith0123@gmail.com; 18308@debbugs.gnu.org
>

[...]


> > I a nutshell, there are cases of node references where the info viewer
> > is not bothered by internal multiple spaces (this cross reference inside
> > bash manual), and other cases where the info viewer cannot handle it
> > (the case of node "(texinfo) @- @hyphenation" pointer in menu entry of
> > upper node).
>
> Emacs already does all that, of course. Just not in the case of the
> menu entries, where the node names are not expected to span more than
> one line.
>

I have checked that in the case of the node line:

File: texinfo.info Node:<node name> ...

the texi2any compiler does correctly the multiblank collapsing.

Basically, trying to recap, if I get it, the work split that you (Eli)
are suggesting between info viewer and texi2any compiler is as follows:

- texi2any must collapse multiple blanks in node names *everywhere*, but
  it is still allowed to break and indent a node name containing a blank
  accross a line in the case of a note.

- info viewer must handle node name split accross lines, but it does not
  need to make multiblank reduction in other-cases

Now, if the above is agreable, then in the case of our problem this
would imply that when texi2any meets that kind of menu entry

* NODE    NAME:: SOME TITLE

It must convert it to within the info file:

* NODE    NAME: NODE NAME. SOME TITLE


Eli:
1) do you agree on my re-caping and suggestion ?

2) do you think that all the same, robustifying the info viewer in the
   case of menu entry has some benefit --- after all this allows:
   2.1) to cope with job done by earlier versions of makeinfo in this
        corner case
   2.2) to have very slightly smaller info file still in this corner case

Gavin & Patrice, do you agree on my suggestion how to evolve texi2any
and stand-alone info viewer ?

> > So, on second thoughts, I am thinking in the end that for consistency,
> > the info viewer not only should, but also _must_ be corrected.
>
> As I said, maybe. But the fact is that the _Texinfo_source_ of the
> Texinfo manual uses different amounts of blanks in this node's name.
> So line breaking and filling in the Info file is not the issue here.
>
> > I am even speculating that in the case of the manual menu entry,
> > probably it was intentional to put more spaces for the entry to read
> > better (as @- and @hyphenation are two different commands, isn't it a
> > good idea to put a little more space between them).
>
> The problem is _inconsistency_, not extra blanks. The number of
> blanks should have been consistent in all the uses of this node name.

I think that the root of that _inconsistency_ problem is that when you
write the following:

* NODE    NAME:: SOME TITLE

"NODE    NAME" has two meanings:

1) it is the menu label, ie what the user will see, so you are not
   allowed to collapse blanks, because this would change what the author
   want to be diplayed to the user

2) it is also the node pointer, so in this case you have to collapse 
   blanks.


Karl: don't you think that *ALSO* the manuel should be changed to be
written as  

* NODE    NAME: NODE NAME. SOME TITLE

In the case of info node `(texinfo) @- @hyphenation'.

Maybe it is not such a good practice to write it the other way round,
because if the author has some intention to display things in some
specific way, then for maintainability that should be explicit in the
way as it is written in the texinfo code.

   Vincent.

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

[Eli Zaretskii]

> From: Vincent Belaïche <Vincent.b.1@hotmail.fr> 
> Cc:  18308@debbugs.gnu.org, Texinfo <bug-texinfo@gnu.org>
> Date: Fri, 22 Aug 2014 15:01:43 +0200
> 
> - texi2any must collapse multiple blanks in node names *everywhere*, but
>   it is still allowed to break and indent a node name containing a blank
>   accross a line in the case of a note.
> 
> - info viewer must handle node name split accross lines, but it does not
>   need to make multiblank reduction in other-cases
> 
> Now, if the above is agreable, then in the case of our problem this
> would imply that when texi2any meets that kind of menu entry
> 
> * NODE    NAME:: SOME TITLE
> 
> It must convert it to within the info file:
> 
> * NODE    NAME: NODE NAME. SOME TITLE

Or it should remove the extra blanks, i.e. produce this:

* NODE NAME:: SOME TITLE

Or it could emit a warning, or even error out.

IOW, I see no reason to silently tolerate such cases.  They are surely
unintended.

> Eli:
> 1) do you agree on my re-caping and suggestion ?

Almost, see above.

> 2) do you think that all the same, robustifying the info viewer in the
>    case of menu entry has some benefit --- after all this allows:
>    2.1) to cope with job done by earlier versions of makeinfo in this
>         corner case
>    2.2) to have very slightly smaller info file still in this corner case

I'm on the fence about this.

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

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

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

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

[Gavin Smith]

On Fri, Aug 22, 2014 at 7:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> Emacs already does all that, of course.  Just not in the case of the
> menu entries, where the node names are not expected to span more than
> one line.
>
>> So, on second thoughts, I am thinking in the end that for consistency,
>> the info viewer not only should, but also _must_ be corrected.
>
> As I said, maybe.  But the fact is that the _Texinfo_source_ of the
> Texinfo manual uses different amounts of blanks in this node's name.
> So line breaking and filling in the Info file is not the issue here.
>

I have deleted an extra space in the menu entries in question in the
Texinfo manual, and following these links works in emacs Info now. I
agree that whitespace normalization is not essential in menu entries.

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

[Gavin Smith]

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

There's a chance for incompatibilities here as well, especially if a
wide range of HTML features is allowed (or JavaScript or CSS). Authors
of generating programs would have to be encouraged to stick within the
approved dialect. Compatibility for different web browsers has been an
ongoing issue for web page writers.

I don't see the point in writing a browser to read a dialect of HTML
used for Texinfo manuals when there are already many web browsers out
there. At the same time I'd like to continue to be able to type "info"
at the command line and get a similar user interface to current, which
I think existing terminal web browsers couldn't provide for every
detail.

I don't think compatibility between Info-generating and reading
programs is a great reason to use HTML instead. It can't be worse than
worrying about how HTML will appear in dozens of different versions of
web browsers.

Are there reasons to use HTML other than compatiblity? For example, if
users would prefer to access locally-installed documentation in a web
browser (instead of using the web browser to look at the manual over
the Internet, or reading it in emacs or in a terminal emulator), maybe
HTML documentation could be installed in a standard location when
packages are installed. An idea I just had is there could be a locally
running documentation webserver daemon that could serve this
documentation, as a kind of "local web app".

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

[Eli Zaretskii]

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

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.

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

[Glenn Morris]

Vincent Belaïche wrote:

[EMACS, EMACS, EMACS]

FYI, it's "Emacs". :)

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

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

That's true -- these tasks are part of the job.

    I don't see the point in writing a browser to read a dialect of HTML
    used for Texinfo manuals when there are already many web browsers out
    there.

This was discussed a few weeks ago.  Ordinary browsers operating on
HTML lack some of the features of Info.  It is not easy to get those
features out of a web browser just by designing the HTML.  We need to
build them onto the ordinary browser facilities.

    Are there reasons to use HTML other than compatiblity?

1. It would interoperate with web browsers.  They would not provide
the added commands/features of Info, but they would be able to display
the manual and you could navigate in it.

2. HTML provides lots of markup and display facilities that Info
lacks.  We could define a new format of our own, but that would
be gratuitous incompatibility -- why not use 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.

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

[Stefan Monnier]

> I think the real fix for this sort of thing is to develop
> a replacement for the Info reader which uses HTML.

I largely agree (tho it doesn't really matter if it's really HTML: it
just needs to be a better format than Info (e.g. one that can be
refilled), and it needs to work within Emacs).

> That's why I was enthusiastic about that project when it was announced.

The only vaguely related project I've heard of recently is the one that
provided an Info-mode-like behavior to view Texinfo docs in your
web browser.
That's very nice, indeed, but I still want to read my docs within Emacs,
so it doesn't really help me,


        Stefan

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

[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 only vaguely related project I've heard of recently is the one that
    provided an Info-mode-like behavior to view Texinfo docs in your
    web browser.

Right.  That would be a replacement for the standalone info program.

    That's very nice, indeed, but I still want to read my docs within Emacs,
    so it doesn't really help me,

We won't have much trouble implementing the same facility inside Emacs.

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

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

[Tom Tromey]

Stefan> The only vaguely related project I've heard of recently is the one that
Stefan> provided an Info-mode-like behavior to view Texinfo docs in your
Stefan> web browser.

Ages ago I wrote a bit of this.
I've appended a patch that adds a few more Info-ish key bindings to eww.
(The patch won't apply as-is because parts of it are already in trunk.)

Most of the bindings from Info-mode will be pretty easy to replicate.

Searching isn't insurmountable but will require a bit of work.

Dealing with the index is maybe the hardest thing.  Here perhaps a new
'rel="index"' attribute would work ok -- this would let the "i" binding
know which links represent the indices, and then enable searching of
those.

Tom

=== modified file 'lisp/net/eww.el'
--- lisp/net/eww.el	2013-06-18 18:04:09 +0000
+++ lisp/net/eww.el	2013-06-19 19:30:57 +0000
@@ -56,6 +56,17 @@
   "Title of current page.")
 (defvar eww-history nil)
 
+(defvar eww-next-url nil)
+(defvar eww-previous-url nil)
+(defvar eww-up-url nil)
+(defvar eww-home-url nil)
+(defvar eww-start-url nil)
+(defvar eww-contents-url nil)
+(defvar eww-index-url nil)
+(defvar eww-info-like-menu nil)
+(defvar eww-xrefs nil)
+(defvar eww-in-menu-class nil)
+
 ;;;###autoload
 (defun eww (url)
   "Fetch URL and render the page."
@@ -64,10 +75,26 @@
     (setq url (concat "http://" url)))
   (url-retrieve url 'eww-render (list url)))
 
+;;;###autoload
+(defun eww-open-file (file)
+  "Render a file using EWW."
+  (interactive "fFile: ")
+  (eww (concat "file://" (expand-file-name file))))
+
 (defun eww-render (status url &optional point)
   (let ((redirect (plist-get status :redirect)))
     (when redirect
       (setq url redirect)))
+  (set (make-local-variable 'eww-next-url) nil)
+  (set (make-local-variable 'eww-previous-url) nil)
+  (set (make-local-variable 'eww-up-url) nil)
+  (set (make-local-variable 'eww-home-url) nil)
+  (set (make-local-variable 'eww-start-url) nil)
+  (set (make-local-variable 'eww-contents-url) nil)
+  (set (make-local-variable 'eww-index-url) nil)
+  (set (make-local-variable 'eww-info-like-menu) nil)
+  (set (make-local-variable 'eww-xrefs) nil)
+  (set (make-local-variable 'eww-in-menu-class) nil)
   (let* ((headers (eww-parse-headers))
 	 (shr-target-id
 	  (and (string-match "#\\(.*\\)" url)
@@ -146,11 +173,62 @@
 	     (input . eww-tag-input)
 	     (textarea . eww-tag-textarea)
 	     (body . eww-tag-body)
-	     (select . eww-tag-select))))
+	     (select . eww-tag-select)
+	     (link . eww-tag-link)
+	     (a . eww-tag-a)
+	     (table . eww-tag-table))))
       (shr-insert-document document)
       (eww-convert-widgets))
     (goto-char (point-min))))
 
+(defun eww-handle-link (cont)
+  (let* ((rel (assq :rel cont))
+  	(href (assq :href cont))
+	(where (assoc
+		;; The text associated with :rel is case-insensitive.
+		(if rel (downcase (cdr rel)))
+		      '(("next" . eww-next-url)
+			;; Texinfo uses "previous", but HTML specifies
+			;; "prev", so recognize both.
+			("previous" . eww-previous-url)
+			("prev" . eww-previous-url)
+			;; HTML specifies "start" but also "contents",
+			;; and Gtk seems to use "home".  Recognize
+			;; them all; but store them in different
+			;; variables so that we can readily choose the
+			;; "best" one.
+			("start" . eww-start-url)
+			("home" . eww-home-url)
+			("contents" . eww-contents-url)
+			("up" . eww-up-url)
+			("index" . eww-index-url)))))
+    (and href
+	 where
+	 (set (cdr where) (cdr href)))))
+
+(defun eww-tag-table (cont)
+  (let ((eww-in-menu-class (equal (cdr (assq :class cont)) "menu")))
+    (if eww-in-menu-class
+	(setq eww-info-like-menu nil))
+    (shr-tag-table cont)
+    (if eww-in-menu-class
+	(setq eww-info-like-menu (nreverse eww-info-like-menu)))))
+
+(defun eww-tag-link (cont)
+  (eww-handle-link cont)
+  (shr-generic cont))
+
+(defun eww-tag-a (cont)
+  (eww-handle-link cont)
+  (let ((start (point))
+	(href (cdr (assoc :href cont))))
+    (shr-tag-a cont)
+    (if href
+	(let ((text (buffer-substring start (point))))
+	  (if eww-in-menu-class
+	      (push (cons text href) eww-info-like-menu)
+	    (push (cons text href) eww-xrefs))))))
+
 (defun eww-update-header-line-format ()
   (if eww-header-line-format
       (setq header-line-format (format-spec eww-header-line-format
@@ -208,7 +286,7 @@
     (erase-buffer))
   (eww-mode))
 
-(defvar eww-mode-map
+(setq eww-mode-map
   (let ((map (make-sparse-keymap)))
     (suppress-keymap map)
     (define-key map "q" 'eww-quit)
@@ -218,8 +296,25 @@
     (define-key map [delete] 'scroll-down-command)
     (define-key map "\177" 'scroll-down-command)
     (define-key map " " 'scroll-up-command)
+    (define-key map "l" 'eww-back-url)
+    (define-key map "n" 'eww-next-url)
     (define-key map "p" 'eww-previous-url)
-    ;;(define-key map "n" 'eww-next-url)
+    (define-key map "u" 'eww-up-url)
+    (define-key map "t" 'eww-top-url)
+    (define-key map "<" 'eww-top-url)
+    (define-key map "T" 'eww-toc)
+    (define-key map "m" 'eww-menu)
+    (define-key map "f" 'eww-follow-reference)
+    (define-key map "1" 'eww-nth-menu-item)
+    (define-key map "2" 'eww-nth-menu-item)
+    (define-key map "3" 'eww-nth-menu-item)
+    (define-key map "4" 'eww-nth-menu-item)
+    (define-key map "5" 'eww-nth-menu-item)
+    (define-key map "6" 'eww-nth-menu-item)
+    (define-key map "7" 'eww-nth-menu-item)
+    (define-key map "8" 'eww-nth-menu-item)
+    (define-key map "9" 'eww-nth-menu-item)
+    (define-key map "0" 'undefined)
     map))
 
 (define-derived-mode eww-mode nil "eww"
@@ -240,7 +335,7 @@
   (setq eww-history nil)
   (kill-buffer (current-buffer)))
 
-(defun eww-previous-url ()
+(defun eww-back-url ()
   "Go to the previously displayed page."
   (interactive)
   (when (zerop (length eww-history))
@@ -248,6 +343,77 @@
   (let ((prev (pop eww-history)))
     (url-retrieve (car prev) 'eww-render (list (car prev) (cadr prev)))))
 
+(defun eww-next-url ()
+  "Go to the page marked `next'.
+A page is marked `next' if rel=\"next\" appears in a <link>
+or <a> tag."
+  (interactive)
+  (if eww-next-url
+      (eww-browse-url (shr-expand-url eww-next-url eww-current-url))
+    (error "No `next' on this page")))
+
+(defun eww-previous-url ()
+  "Go to the page marked `previous'.
+A page is marked `previous' if rel=\"previous\" appears in a <link>
+or <a> tag."
+  (interactive)
+  (if eww-previous-url
+      (eww-browse-url (shr-expand-url eww-previous-url eww-current-url))
+    (error "No `previous' on this page")))
+
+(defun eww-up-url ()
+  "Go to the page marked `up'.
+A page is marked `up' if rel=\"up\" appears in a <link>
+or <a> tag."
+  (interactive)
+  (if eww-up-url
+      (eww-browse-url (shr-expand-url eww-up-url eww-current-url))
+    (error "No `up' on this page")))
+
+(defun eww-top-url ()
+  "Go to the page marked `top'.
+A page is marked `top' if rel=\"start\", rel=\"home\", or rel=\"contents\"
+appears in a <link> or <a> tag."
+  (interactive)
+  (let ((best-url (or eww-start-url
+		      eww-contents-url
+		      eww-home-url)))
+    (if best-url
+	(eww-browse-url (shr-expand-url best-url eww-current-url))
+      (error "No `top' for this page"))))
+
+(defun eww-toc ()
+  "Go to the page marked `contents'.
+A page is marked `contents' if rel=\"contents\" appears in a <link>
+or <a> tag."
+  (interactive)
+  (if eww-contents-url
+      (eww-browse-url (shr-expand-url eww-contents-url eww-current-url))
+    (error "No `contents' on this page")))
+
+(defun eww-follow-reference (ref)
+  (interactive
+   (list (completing-read "Menu item: " eww-xrefs nil t))) ;; FIXME history
+  (eww-browse-url (shr-expand-url (cdr (assoc ref eww-xrefs))
+				  eww-current-url)))
+
+(defun eww-menu (ref)
+  (interactive
+   (list (completing-read "Menu item: " eww-info-like-menu nil t))) ;; FIXME history
+  (eww-browse-url (shr-expand-url (cdr (assoc ref eww-info-like-menu))
+				  eww-current-url)))
+
+(defun eww-nth-menu-item ()
+  (interactive)
+  (let* ((n
+	  (- (aref (this-command-keys) (1- (length (this-command-keys)))) ?1))
+	 (menu-item (nth n eww-info-like-menu)))
+    (if menu-item
+	(eww-browse-url (shr-expand-url (cdr menu-item) eww-current-url))
+      (if eww-info-like-menu
+	  (error "Too few items in menu")
+	(error "No menu in this page")))))
+
 (defun eww-reload ()
   "Reload the current page."
   (interactive)

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

[Stefan Monnier]

>     That's very nice, indeed, but I still want to read my docs within Emacs,
>     so it doesn't really help me,
> We won't have much trouble implementing the same facility inside Emacs.

The proof is in the pudding.  IOW I don't believe it's that easy.


        Stefan

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

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

    Stefan> The only vaguely related project I've heard of recently is the one that
    Stefan> provided an Info-mode-like behavior to view Texinfo docs in your
    Stefan> web browser.

Someone said here a few weeks ago he was working on something like 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.

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

[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 very nice, indeed, but I still want to read my docs within Emacs,
    >     so it doesn't really help me,
    > We won't have much trouble implementing the same facility inside Emacs.

    The proof is in the pudding.  IOW I don't believe it's that easy.

The reason I think it is easy is that it will be looking at HTML
made from Texinfo sources and designed to make it easy to
program the various operations of 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.

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

[Glenn Morris]

Gavin Smith wrote:

> I have deleted an extra space in the menu entries in question in the
> Texinfo manual, and following these links works in emacs Info now. I
> agree that whitespace normalization is not essential in menu entries.

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

[Gavin Smith]

(adding bug-texinfo)

On Fri, Aug 22, 2014 at 11:04 PM, Vincent Belaïche
<Vincent.b.1@hotmail.fr> wrote:
> 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)
>

It might be worth asking on emacs-devel about this to see if anyone
wants to implement it or has ideas about how it could work.

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

Seems like a good idea to me. Would help for links between manuals and
for finding pages in other languages. Are there any guidelines about
how to translate Texinfo documents?

> 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

Having translated node names isn't as important because there would be
translated headers in the contents of files/nodes saying what section
we're in. The main use would be the status bar in a browser giving the
current node, and pointers or references to other nodes. I understand
it is not ideal to read a cross-reference in another language. Maybe
anchors with translated node names could be used instead? That would
work for everything (cross-references, pointers) apart from the node
name that is displayed in a status bar. Maybe makeinfo would have to
be modified to recognize that a menu in a node using anchor names is
referring to the child nodes properly.

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

[Vincent Belaïche]

Answers inserted below...

----------------------------------------
> Date: Sun, 31 Aug 2014 23:37:06 +0100
> Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
> From: gavinsmith0123@gmail.com
> To: Vincent.b.1@hotmail.fr
> CC: 18308@debbugs.gnu.org; bug-texinfo@gnu.org
>
> (adding bug-texinfo)
>
> On Fri, Aug 22, 2014 at 11:04 PM, Vincent Belaïche
> <Vincent.b.1@hotmail.fr> wrote:
>> 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)
>>
>
> It might be worth asking on emacs-devel about this to see if anyone
> wants to implement it or has ideas about how it could work.
>
>> 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.
>
> Seems like a good idea to me. Would help for links between manuals and
> for finding pages in other languages. Are there any guidelines about
> how to translate Texinfo documents?
>

Currently the usual practice is that a translated document is just another document with some -xx ending in the base name (where xx refers to the language, e.g. fr for French). 

In my opinion an alternative method would be that translated document should rather bare exactly the same name but just be in a language specific directory named xx, with some fall backs to another language (meaning ../oo, where oo refers to the other language) when manual does not exists.

I think that the alternative method is closer to what people usually do for Web sites, in which each language is its own tree replica (file/directory names are same, but only file contents differ).

>> 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
>
> Having translated node names isn't as important because there would be
> translated headers in the contents of files/nodes saying what section
> we're in. The main use would be the status bar in a browser giving the
> current node, and pointers or references to other nodes. I understand
> it is not ideal to read a cross-reference in another language. Maybe
> anchors with translated node names could be used instead? That would
> work for everything (cross-references, pointers) apart from the node
> name that is displayed in a status bar. Maybe makeinfo would have to
> be modified to recognize that a menu in a node using anchor names is
> referring to the child nodes properly.

Menus are precisely the only place where you don't need any change in Texinfo, as you can do:

* Translated node name: true node name. Some description

@node true node name

and the viewer is supposed to show only "Translated node name".

What I was meaning is that the viewer should be configurable to show either the "node path" with translated names or true names.

In the case of nodes that are not referred by any menu, like the top node, or node accessed only by cross reference, there aren't currently any provision in Texinfo to povide a node name translation. That could be some command @localenodename to give that translation inside the node.

  Vincent.



 		 	   		  

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

[Gavin Smith]

On Mon, Sep 1, 2014 at 8:40 PM, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
>> Having translated node names isn't as important because there would be
>> translated headers in the contents of files/nodes saying what section
>> we're in. The main use would be the status bar in a browser giving the
>> current node, and pointers or references to other nodes. I understand
>> it is not ideal to read a cross-reference in another language. Maybe
>> anchors with translated node names could be used instead? That would
>> work for everything (cross-references, pointers) apart from the node
>> name that is displayed in a status bar. Maybe makeinfo would have to
>> be modified to recognize that a menu in a node using anchor names is
>> referring to the child nodes properly.
>
> Menus are precisely the only place where you don't need any change in Texinfo, as you can do:
>
> * Translated node name: true node name. Some description
>
> @node true node name
>
> and the viewer is supposed to show only "Translated node name".
>

I can imagine cases where a menu label is something other than the
node name, for example if the document author wants to give a more
extended description of what the node is about. Anyway, names of
targets are not usually hidden (in the standalone Info browser, at
least).

> What I was meaning is that the viewer should be configurable to show either the "node path" with translated names or true names.
>
> In the case of nodes that are not referred by any menu, like the top node, or node accessed only by cross reference, there aren't currently any provision in Texinfo to povide a node name translation. That could be some command @localenodename to give that translation inside the node.

Something like this could be done by treating an anchor as a synonym
for a node if it refers to byte 0 of the node. If someone selected or
followed a reference to such an anchor, its name could be displayed
instead of the node. There would still be the problem of how makeinfo
would do "implicit pointer creation" with the right node names.

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

[Karl Berry]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1749 bytes --]

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

    Currently the usual practice is that a translated document is just
    another document with some -xx ending in the base name (where xx refers
    to the language, e.g. fr for French). 

True.

    In my opinion an alternative method would be that translated document
    should rather bare exactly the same name but just be in a language
    specific directory named xx, with some fall backs to another language

No question that that is a well-known alternative approach.

    * Translated node name: true node name. Some description
    @node true node name
    and the viewer is supposed to show only "Translated node name".

As Gavin says, that is not correct.  Both parts of the node name are
intended to be shown.  The existing use of this feature is to make short
menu item abbreviations, e.g., for the sake of completion or just ease
of reading.  For example, in the Texinfo manual, the HTML Cross
References section has a @menu like this:

@menu
* Link Basics:       HTML Xref Link Basics.
* Node Expansion:    HTML Xref Node Name Expansion.
..


Whatever such a hypothetical texinfo-light needs to do, fine.  We should
think about that separately.  It need not affect what Texinfo does.
Seems like two very different cases to me.  Let's not try to shoehorn
existing Texinfo features into things that are far outside their intent
and practice.

A discussion of such a texinfo-light (not a name I would advocate,
either) should presumably take place on emacs-devel, not in a debian bug
for Texinfo.

k

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

[Vincent Belaïche]

Just to clarify that I was suggesting three completely different things:

One first thing was better support of internationalization for *Manuals*, in that context I was speaking about node name translation for presentation to user (there should remain a node true name that should remain the same whatever the translation. Ok, sorry if I misunderstood the rationale for the menu entries.

One second thing was internationalisation for *DocStrings*, in that context I was suggesting that docstring could contain some link to some manual variable or function description, so switching the Help language based on configured locale would just mean switching to the correct manual translation. 

BTW, replacing docstring by jump to manual is basically what calc already does, with its "h f" and "h k" commands. However it does it in a language dependent way because it does not use the "position within the node" (call it PWTN) in the command/variable index --- maybe the reason for such an implementation is that when this feature was made available in calc,, info  was not supporting so well PWTN --- but instead uses only the node pointer, and then seaches some string in the node to find the position.

One third thing is that even plain docstring format itself is language dependant. Only for that third item I was suggesting that a better format for docstrings would be some sort of texinfo-light (I think that texinfmt.el already support some lighter texinfo and could be some starting point for adding such a feature).

So in a nutshell the evolved docstring would contain some header indicating
- is that legacy format
- is that texinfo-light format
- do we have a pointer to some manual to be used instead when available and sought for at the configured locale location --- note that the pointer needs only to indentify the manual itself, the variable or function name is already known what you do C-h f or C-h k.

   Vincent.

----------------------------------------
> Date: Mon, 1 Sep 2014 21:53:55 +0000
> From: karl@freefriends.org
> To: vincent.b.1@hotmail.fr; 18308@debbugs.gnu.org; bug-texinfo@gnu.org
> Subject: RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
>
>> 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.> Seems
>
> Currently the usual practice is that a translated document is just
> another document with some -xx ending in the base name (where xx refers
> to the language, e.g. fr for French).
>
> True.
>
> In my opinion an alternative method would be that translated document
> should rather bare exactly the same name but just be in a language
> specific directory named xx, with some fall backs to another language
>
> No question that that is a well-known alternative approach.
>
> * Translated node name: true node name. Some description
> @node true node name
> and the viewer is supposed to show only "Translated node name".
>
> As Gavin says, that is not correct. Both parts of the node name are
> intended to be shown. The existing use of this feature is to make short
> menu item abbreviations, e.g., for the sake of completion or just ease
> of reading. For example, in the Texinfo manual, the HTML Cross
> References section has a @menu like this:
>
> @menu
> * Link Basics: HTML Xref Link Basics.
> * Node Expansion: HTML Xref Node Name Expansion.
> ..
>
>
> Whatever such a hypothetical texinfo-light needs to do, fine. We should
> think about that separately. It need not affect what Texinfo does.
> Seems like two very different cases to me. Let's not try to shoehorn
> existing Texinfo features into things that are far outside their intent
> and practice.
>
> A discussion of such a texinfo-light (not a name I would advocate,
> either) should presumably take place on emacs-devel, not in a debian bug
> for Texinfo.
>
> k