bug#22306: 24.5; Unhide --no-line-directive Documentation

bug#22306: 24.5; Unhide --no-line-directive Documentation

[James Muchow]

This bug report will be sent to the Bug-GNU-Emacs mailing list
and the GNU bug tracker at debbugs.gnu.org.  Please check that
the From: line contains a valid email address.  After a delay of up
to one day, you should receive an acknowledgment at that address.

Please write in English if possible, as the Emacs maintainers
usually do not have translators for other languages.

Please describe exactly what actions triggered the bug, and
the precise symptoms of the bug.  If you can, give a recipe
starting from `emacs -Q':

In trying to create a TAGS file, etags would process the
#line directive in various source files and produce TAGS 
files that were unusable because the "file name" included
would be unavailable causing the tags-search to exit before
having seen all files.

I spent a lot of time coming up with a solution to avoid
any files that contained a line directive when the solution
I really needed was already present: --no-line-directive.
It is, however, undocumented and thus the only way to know
about it is to download the source. I downloaded the source
to try and find out what etags was doing wrong with #line
when I discovered this undocumented option.

I see from the source that the --no-line-directive is hidden
by the PRINT_UNDOCUMENTED_OPTIONS_HELP; I think it would be
helpful for others to remove this restriction.
 
If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
For information about debugging Emacs, please read the file
/usr/local/share/emacs/24.5/etc/DEBUG.


In GNU Emacs 24.5.1 (amd64-portbld-freebsd10.1, GTK+ Version 2.24.28)
 of 2015-10-23 on 101amd64-default-job-07
Configured using:
 `configure --localstatedir=/var --disable-acl --with-dbus
 --without-file-notification --with-gconf --with-gif --with-gnutls
 --with-gsettings --with-jpeg --with-m17n-flt --with-imagemagick
 --with-libotf --with-png --with-toolkit-scroll-bars --with-rsvg
 --with-tiff --with-x --with-xft --with-xim --with-xml2 --with-xpm
 --with-x-toolkit=gtk2 --with-sound=oss --x-libraries=/usr/local/lib
 --x-includes=/usr/local/include --prefix=/usr/local
 --mandir=/usr/local/man --infodir=/usr/local/share/emacs/info/
 --build=amd64-portbld-freebsd10.1 'CFLAGS=-O2 -pipe -fstack-protector
 -fno-strict-aliasing' CPPFLAGS=-I/usr/local/include 'LDFLAGS=
 -L/usr/local/lib -Wl,-rpath=/usr/lib:/usr/local/lib -fstack-protector''

Important settings:
  value of $LANG: C
  locale-coding-system: nil

Major mode: Fundamental

Minor modes in effect:
  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
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message idna format-spec
rfc822 mml easymenu mml-sec mm-decode mm-bodies mm-encode mail-parse
rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045
ietf-drums mm-util help-fns mail-prsvr mail-utils xterm time-date
tooltip electric uniquify ediff-hook vc-hooks lisp-float-type mwheel
x-win x-dnd 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
dbusbind dynamic-setting system-font-setting font-render-setting
move-toolbar gtk x-toolkit x multi-tty emacs)

Memory information:
((conses 16 76429 6886)
 (symbols 48 17651 0)
 (miscs 40 71 128)
 (strings 32 9046 4687)
 (string-bytes 1 248303)
 (vectors 16 7038)
 (vector-slots 8 341334 33197)
 (floats 8 65 287)
 (intervals 56 190 119)
 (buffers 960 12))

bug#22306: 24.5; Unhide --no-line-directive Documentation

[Eli Zaretskii]

> From: James Muchow <jim_muchow@dell.com>
> Date: Mon, 4 Jan 2016 19:41:28 +0000
> 
> In trying to create a TAGS file, etags would process the
> #line directive in various source files and produce TAGS 
> files that were unusable because the "file name" included
> would be unavailable causing the tags-search to exit before
> having seen all files.
> 
> I spent a lot of time coming up with a solution to avoid
> any files that contained a line directive when the solution
> I really needed was already present: --no-line-directive.
> It is, however, undocumented and thus the only way to know
> about it is to download the source. I downloaded the source
> to try and find out what etags was doing wrong with #line
> when I discovered this undocumented option.
> 
> I see from the source that the --no-line-directive is hidden
> by the PRINT_UNDOCUMENTED_OPTIONS_HELP; I think it would be
> helpful for others to remove this restriction.

Francesco,

Are there any reasons to keep this option (and a few others) hidden
from the user eyes?

Thanks.

bug#22306: 24.5; Unhide --no-line-directive Documentation

[Francesco Potortì]

>> From: James Muchow <jim_muchow@dell.com>
>> Date: Mon, 4 Jan 2016 19:41:28 +0000
>> 
>> In trying to create a TAGS file, etags would process the
>> #line directive in various source files and produce TAGS 
>> files that were unusable because the "file name" included
>> would be unavailable causing the tags-search to exit before
>> having seen all files.
>> 
>> I spent a lot of time coming up with a solution to avoid
>> any files that contained a line directive when the solution
>> I really needed was already present: --no-line-directive.
>> It is, however, undocumented and thus the only way to know
>> about it is to download the source. I downloaded the source
>> to try and find out what etags was doing wrong with #line
>> when I discovered this undocumented option.
>> 
>> I see from the source that the --no-line-directive is hidden
>> by the PRINT_UNDOCUMENTED_OPTIONS_HELP; I think it would be
>> helpful for others to remove this restriction.
>
>Francesco,
>
>Are there any reasons to keep this option (and a few others) hidden
>from the user eyes?

For this specific otion, the logs say that I undocumented it in 2002.
As far as I can recall, this was because the option seemed too much
technical to me, that is of little use and difficult to explain.  I
think I adopted the same criterion for undocumenting the other options.

bug#22306: 24.5; Unhide --no-line-directive Documentation

[James Muchow]

> From: Francesco Potortì [mailto:pot@gnu.org] 
> Sent: Saturday, January 09, 2016 5:27 PM
>>> From: James Muchow <jim_muchow@dell.com>
>>> Date: Mon, 4 Jan 2016 19:41:28 +0000
>>> 
>>> In trying to create a TAGS file, etags would process the
>>> #line directive in various source files and produce TAGS 
>>> files that were unusable because the "file name" included
>>> would be unavailable causing the tags-search to exit before
>>> having seen all files.
>>> 
>>> I spent a lot of time coming up with a solution to avoid
>>> any files that contained a line directive when the solution
>>> I really needed was already present: --no-line-directive.
>>> It is, however, undocumented and thus the only way to know
>>> about it is to download the source. I downloaded the source
>>> to try and find out what etags was doing wrong with #line
>>> when I discovered this undocumented option.
>>> 
>>> I see from the source that the --no-line-directive is hidden
>>> by the PRINT_UNDOCUMENTED_OPTIONS_HELP; I think it would be
>>> helpful for others to remove this restriction.
>>
>> Francesco,
>> 
>> Are there any reasons to keep this option (and a few others) hidden
>> from the user eyes?
>
> For this specific otion, the logs say that I undocumented it in 2002.
> As far as I can recall, this was because the option seemed too much
> technical to me, that is of little use and difficult to explain.  I
> think I adopted the same criterion for undocumenting the other options.

First of all thanks for cleaning up my request and getting rid of
all the extraneous verbiage. I've never filed a bug report before,
so I didn't quite know what to expect. Anyway...

I am aware that the documentation hiding was done years ago. As to
whether it is too technical or not; the fact is that in our
environment, the TAGS files I produced are useless (30M of 
useless) and that was quickly diagnosed to those files that use 
the #line directive.

Resolving this issue involved, as I wrote, a lot of time when the
solution was already present the whole time. A solution of which
I was unaware because it was deemed too technical.

I now know of this option, so I could take the "I don't care, I
got mine" approach, but I thought that such a trivial fix might
be turn out to be helpful to someone else. But YMMV, I'll leave
the eventual resolution in your hands.

bug#22306: 24.5; Unhide --no-line-directive Documentation

[Eli Zaretskii]

> Date: Sun, 10 Jan 2016 00:26:55 +0100
> From: Francesco Potortì <pot@gnu.org>
> Cc: 22306@debbugs.gnu.org, James Muchow <jim_muchow@dell.com>
> 
> >Francesco,
> >
> >Are there any reasons to keep this option (and a few others) hidden
> >from the user eyes?
> 
> For this specific otion, the logs say that I undocumented it in 2002.

My forensic investigation of the history indicates that it was
first introduced in 2002, and undocumented in 2007.

> As far as I can recall, this was because the option seemed too much
> technical to me, that is of little use and difficult to explain.  I
> think I adopted the same criterion for undocumenting the other options.

Well, it seems this option is useful when the original file is no
longer available, which is a legitimate, albeit rare, use case.  So I
un-hided it, and also documented it in etags.1 as the fire-escape in
these rare use cases.

I'm therefore marking this bug done.

Thanks.