[gnu.org #181558] format error in html mono web page

[gnu.org #181558] format error in html mono web page

[Corey Goldberg via RT]

Hello.
please see below..  this was forwarded to Webmasters by RMS, but it is 
sort of out of our scope and more in the realm of what emacs-devel does. 
Can someone take a look at this?

regards,
Corey (GNU Webmasters)


>Subject: [mihu@olympus.net: format error in html mono web page]
>Date: Wed, 31 Mar 2004 23:41:53 -0500
>To: webmasters@gnu.org
>From: Richard Stallman <rms@gnu.org>
>
>------- Start of forwarded message -------
>From: "michael humphrey" <mihu@olympus.net>
>To: <bug-gnu-emacs@gnu.org>
>
>re:
>http://www.gnu.org/software/emacs/manual/html_mono/emacs.html
>This manual is available in the following formats:=20
>formatted in HTML (3124K characters) entirely on one web page.=20
>
>this web page has a formatting error under the category
>M.7.5.3 Undoing Version Control Actions ...
>
>starting with the text,
>However, it is impossible to unexpand the RCS ...



--------------------------------------------
> [karl - Thu Apr 01 20:02:15 2004]:
> 
> 
> I'm guessing this was a bug in the emacs manual for 21.2, they
> probably
> wrote $Log$ in the Texinfo source (namely files.texi).  In 21.3, 
>it now says:
>   However, it is impossible to unexpand the RCS @samp{@w{$}Log$}...
> which should avoid the unwanted expansion.
> 
> So, if the online manual was updated to the output for 21.3, it 
> would be
> better.  (Not to mention that is obviously desirable anyway.)
> 
> I'm not sure it should be up to webmasters to do this; generally, the
> package maintainers are supposed to.  But if you feel like it, you 
> might
> try the gendocs.sh script, as described in
> http://www.gnu.org/prep/maintain_25.html
> (Of course there are other ways to accomplish the same end.)
> 
> Alternatively, you could bounce it back to emacs-devel@gnu.org. 
> Surely
> someone there would be willing.

Re: [gnu.org #181558] format error in html mono web page

[Richard Stallman]

I looked at this, and I think that the problem occurred when Dave
checked the formatter HTML file into CVS.  That is because the file
contains something that looks like an RCS keyword.  It should contain
$Log$.

The long-term fix, perhaps, is to change makeinfo to output some
HTML no-op there which will prevent CVS from recognizing the "keyword".
For the mean time, Dave, could you do this over and manually
insert a suitable no-op?

  However, it is impossible to unexpand the RCS <SAMP>`$Log: emacs.html,v $
  However, it is impossible to unexpand the RCS <SAMP>`Revision 1.1  2003/10/30 01:27:33  sinuhe
  However, it is impossible to unexpand the RCS <SAMP>`Add emacs manual.
  However, it is impossible to unexpand the RCS <SAMP>`'</SAMP> header

Or could you turn off RCS keyword substitution for the HTML files
of the Emacs manual, and regenerate these and check them in?

Re: [gnu.org #181558] format error in html mono web page

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> I looked at this, and I think that the problem occurred when Dave
> checked the formatter HTML file into CVS.  That is because the file
> contains something that looks like an RCS keyword.  It should contain
> $Log$.

This is an interesting problem when the output of a file with
description of some feature is processed according to its own
description on literal strings it contains.

The aforementioned HTML file contains also other expanded RCS keywords:
the node "(emacs)Version Headers" has $Id$ expanded in several places.
For example, in the following paragraph:

  It is often necessary to use "superfluous" backslashes when
writing the strings that you put in this variable.  For instance, you
might write <CODE>"$Id\$"</CODE> rather than <CODE>"$Id: emacs.html,v 1.1 2003/10/30 01:27:33 sinuhe Exp $"</CODE>.  The extra
backslash prevents the string constant from being interpreted as a
header, if the Emacs Lisp file containing it is maintained with
version control.

the $Id$ keyword is expanded while $Id\$ is not.

One possibility is to take the advice from this paragraph and to quote
all RCS keywords in the Emacs manual, with explanations for the reader
of the manual how s?he could get the right value from a quoted string.

> The long-term fix, perhaps, is to change makeinfo to output some
> HTML no-op there which will prevent CVS from recognizing the "keyword".

Changing makeinfo to add some HTML no-op, or e.g. to replace a dollar
sign by the HTML numerical character reference in RCS keywords will
definitely work for HTML output.  But one can imagine a situation with
the need to put other Texinfo output file types under version control
where it will not work.  For example, I don't see how RCS keywords
could be prevented from expansion in Info output files.

> Or could you turn off RCS keyword substitution for the HTML files
> of the Emacs manual, and regenerate these and check them in?

This problem exists not only in the HTML files like

http://www.gnu.org/software/emacs/manual/html_node/emacs_141.html
http://www.gnu.org/software/emacs/manual/html_node/emacs_158.html
http://www.gnu.org/software/emacs/manual/html_chapter/emacs_16.html

but also in other files, e.g.

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

and some Emacs Lisp files under webcvs/emacs.

I don't know exactly about workflow for putting files on the GNU Web
server, but generally I'd rather suggest not to put generated files
under version control.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: [gnu.org #181558] format error in html mono web page

[Adrian Aichner]

>>>>> "Juri" == Juri Linkov <juri@jurta.org> writes:

    Juri> One possibility is to take the advice from this paragraph
    Juri> and to quote all RCS keywords in the Emacs manual, with
    Juri> explanations for the reader of the manual how s?he could get
    Juri> the right value from a quoted string.

Hello Juri, that is the approach taken in the XEmacs version of
man/xemacs/files.texi, producing this output:

   The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS.
(The actual strings inserted do not have the backslashes in them.  They
were placed in the Info source file so that the strings don't get
interpreted as version-control headers when the Info source files are
maintained under version control.) You can specify other headers to

Regards,

-- 
Adrian Aichner
 mailto:adrian@xemacs.org
 http://www.xemacs.org/

Re: [gnu.org #181558] format error in html mono web page

[Richard Stallman]

    and some Emacs Lisp files under webcvs/emacs.

Could you explain one example of the problem you saw in the Lisp files?
I presume if there is a live RCS keyword in a Lisp file
that it is meant to expand--so it's not clear what the problem would be.
(Many of these keywords are going to be removed soon, I believe,
but that's a different issue.)

    I don't know exactly about workflow for putting files on the GNU Web
    server, but generally I'd rather suggest not to put generated files
    under version control.

The whole contents of the site are a mirror of what's in CVS.

Re: [gnu.org #181558] format error in html mono web page

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
>     and some Emacs Lisp files under webcvs/emacs.
>
> Could you explain one example of the problem you saw in the Lisp files?
> I presume if there is a live RCS keyword in a Lisp file
> that it is meant to expand--so it's not clear what the problem would be.
> (Many of these keywords are going to be removed soon, I believe,
> but that's a different issue.)

Those are RCS keywords from Emacs Lisp files under the directory
`/webcvs/emacs/windows/ntemacs/' which are referred from the GNU Emacs
FAQ for Windows.  These Emacs Lisp files are imported from external
sources and are apparently not intended for development under webcvs.
But all their RCS keywords were expanded with log entries like the
following:

;; $Log: bat-mode.el,v $
;; Revision 1.1  2001/02/13 00:52:03  webcvs
;; import ./software/emacs/windows/ntemacs/contrib

>     I don't know exactly about workflow for putting files on the GNU Web
>     server, but generally I'd rather suggest not to put generated files
>     under version control.
>
> The whole contents of the site are a mirror of what's in CVS.

Then it really seems the best way to go is to disable RCS keyword
expansion for CVS import.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: [gnu.org #181558] format error in html mono web page

[Richard Stallman]

    Those are RCS keywords from Emacs Lisp files under the directory
    `/webcvs/emacs/windows/ntemacs/' which are referred from the GNU Emacs
    FAQ for Windows.

I don't know what `/webcvs' has to do with it, but I found these files in
`http://www.gnu.org/software/emacs/windows/ntemacs/contrib'.

Such a directory should not exist.  These files should not be
distributed by the FSF.  We don't have papers for them, and they only
work on Microsoft Windows.  Some of them are encryption code I did not
know about.  How did this directory get created anyway?

I will have the directory deleted a week from today.  In the mean
time, if someone wants to argue why we should install a specific file
into Emacs, or why we should preserve some specific file, I'm willing
to listen.

Re: [gnu.org #181558] format error in html mono web page

[Andre Spiegel]

On Sun, 2004-04-04 at 01:40, Richard Stallman wrote:

> Or could you turn off RCS keyword substitution for the HTML files
> of the Emacs manual, and regenerate these and check them in?

I also think this is the best solution.  There is no reason ever to use
keyword substitution on a generated file.