file variables and man pages with preprocessors

file variables and man pages with preprocessors

[Werner LEMBERG]

There is a convention in man pages to mark them whether a preprocessor
has to be used or not.  The first line must resemble

  '\" <string>

where <string> is a combination of letters which identify the used
preprocessor.  For example, `p' and `t' stand for pic and tbl,
respectively:

  '\" tp

However, if a man page starts with such a comment, local file
variables can't be placed into the first line and are no longer
recognized by Emacs.

I thus ask to handle files which start with

  '\"

similar to shell scripts, this is, to take the *second* line for file
variables.

Another reason for this request is the forthcoming release of groff
which contains a preprocessor, preconv, to handle man pages in various
input encodings, and which recognizes Emacs coding tags (within a file
variable at the top of a file).


    Werner

Re: file variables and man pages with preprocessors

[Richard Stallman]

    I thus ask to handle files which start with

      '\"

    similar to shell scripts, this is, to take the *second* line for file
    variables.

It sounds ok to me, but does anyone see a likely problem?

Re: file variables and man pages with preprocessors

[Glenn Morris]

Richard Stallman wrote:

> It sounds ok to me, but does anyone see a likely problem?

It seems a little ugly to shoe-horn yet another special case in, when
local variables can just go at the end of the file.

Re: file variables and man pages with preprocessors

[Richard Stallman]

    > It sounds ok to me, but does anyone see a likely problem?

    It seems a little ugly to shoe-horn yet another special case in, when
    local variables can just go at the end of the file.

It is a lot more convenient to use -*- -*- for something simple.

Re: file variables and man pages with preprocessors

[Werner LEMBERG]

>     It seems a little ugly to shoe-horn yet another special case in,
>     when local variables can just go at the end of the file.
> 
> It is a lot more convenient to use -*- -*- for something simple.

Well, preconv acts as a filter -- as do (almost) all components in
groff -- thus reading something from the `end of a file' (a) needs a
temporary buffer since the input data stream is `stdin' in most cases
and (b) isn't implemented in preconv due to (a).

Additionally, I'm not aware of any other special case except this one;
man pages act this way since at least 20 years AFAIK.


    Werner

Re: file variables and man pages with preprocessors

[Richard Stallman]

    Well, preconv acts as a filter -- as do (almost) all components in
    groff -- thus reading something from the `end of a file' (a) needs a
    temporary buffer since the input data stream is `stdin' in most cases
    and (b) isn't implemented in preconv due to (a).

I don't understand this.  What is preconv, and what does it have to do
with visiting these files in Emacs?

Re: file variables and man pages with preprocessors

[Werner LEMBERG]

>     Well, preconv acts as a filter -- as do (almost) all components
>     in groff -- thus reading something from the `end of a file' (a)
>     needs a temporary buffer since the input data stream is `stdin'
>     in most cases and (b) isn't implemented in preconv due to (a).
> 
> I don't understand this.  What is preconv, and what does it have to
> do with visiting these files in Emacs?

`preconv' is a new preprocessor (currently in the CVS of groff only)
which converts man pages in any input encoding to something groff can
digest.  It supports the GNU Emacs convention for coding tags at the
beginning of a file but not at the end of a file for the reasons given
above.

Consider this example of troff.man (omitting some lines for brevity):

  '\" t
  .ig
    troff.man
    Copyright (C) ...
  ..
  .
  .TH TROFF 1 "2000-10-20" "Groff Version 1.2.3"
  .SH NAME
  troff \- the troff processor of the groff text formatting system

Here, the first line indicates that the `tbl' preprocessor is needed;
and the `man' program will call it due to this line.

Now assume that I want to have this man page in, say, German.  It how
has to start with

  '\" t
  .\" -*- coding: latin-1 -*-
  .ig
    troff.man
    Copyright (C) ...
  ..
  .
  .TH TROFF 1 "2000-10-20" "Groff Version 1.2.3"
  .SH NAME
  troff \- Der troff-Prozessor des groff-Textformatierungssystems

to use latin-1 (or another suitable encoding like utf-8).

Opening such a file currently in Emacs doesn't select the proper file
encoding.


    Werner

Re: file variables and man pages with preprocessors

[Glenn Morris]

Werner LEMBERG wrote:

> `preconv' is a new preprocessor (currently in the CVS of groff only)
> which converts man pages in any input encoding to something groff can
> digest.  It supports the GNU Emacs convention for coding tags at the
> beginning of a file but not at the end of a file for the reasons given
> above.

You said this in your very first post and I totally missed it, sorry.
I think this makes the decision a no-brainer.

Re: file variables and man pages with preprocessors

[Richard Stallman]

Thanks.  I think that explains enough.

Would someone please install this change?

Re: file variables and man pages with preprocessors

[Werner LEMBERG]

> Would someone please install this change?

If someone shows me where this should be handled, I'll fix it by
myself and apply the changes to the CVS.  I wasn't able to find the
location in the sources where the shebang is handled
w.r.t. recognizing the encoding tag.


    Werner

Re: file variables and man pages with preprocessors

[Glenn Morris]

Werner LEMBERG wrote:

> If someone shows me where this should be handled, I'll fix it by
> myself and apply the changes to the CVS.  I wasn't able to find the
> location in the sources where the shebang is handled
> w.r.t. recognizing the encoding tag.

set-auto-mode-1 in files.el

If the #! special case is documented in the manuals, the \" one
probably should be too.

Re: file variables and man pages with preprocessors

[Werner LEMBERG]

> > If someone shows me where this should be handled, I'll fix it by
> > myself and apply the changes to the CVS.  I wasn't able to find
> > the location in the sources where the shebang is handled
> > w.r.t. recognizing the encoding tag.
> 
> set-auto-mode-1 in files.el

Thanks.  Here's what I'm planning to commit:


--- files.el.old	2007-11-11 14:20:14.000000000 +0100
+++ files.el	2007-11-12 12:19:03.000000000 +0100
@@ -2428,7 +2428,12 @@
                             ;; put them in the first line of
                             ;; such a file without screwing up
                             ;; the interpreter invocation.
-                            (and (looking-at "^#!") 2)) t)
+                            ;; The same holds for
+                            ;;   '\"
+                            ;; in man pages (preprocessor
+                            ;; magic for the `man' program).
+                            (and (or (looking-at "^#!")
+                                     (looking-at "^'\\\\\"")) 2)) t)
      (progn
        (skip-chars-forward " \t")
        (setq beg (point))


> If the #! special case is documented in the manuals, the \" one
> probably should be too.

Yes, will do.


    Werner

Re: file variables and man pages with preprocessors

[Glenn Morris]

Werner LEMBERG wrote:

> +                            (and (or (looking-at "^#!")
> +                                     (looking-at "^'\\\\\"")) 2)) t)

Why not (looking-at "^\\(#!\\|'\\\\\"\\)") ?

Re: file variables and man pages with preprocessors

[Werner LEMBERG]

> Why not (looking-at "^\\(#!\\|'\\\\\"\\)") ?

OK.


    Werner