Re: MH-E manual update

[Bill Wohler <wohler@newt.com>]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> Bill Wohler wrote:
> 
>    >     @samp{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not <<<<<<<
>    >     correct, the body fragment will not be highlighted with the face
>    >     @code{mh-folder-body}.
>    > 
>    > I think this usage is not a very good idea: @samp{foo} is typeset as
>    > `foo', so you will have here quotes inside quotes.  I suggest to lose
>    > the inner quotes, since they are redundant IMO.
> 
>    They aren't redundant since the user actually has to enter the quotes in
>    his value. I agree that having quotes inside quotes doesn't look good,
>    but it's probably a necessary evil to be technically correct.
> 
> Without the double quotes, the doubling up of backslashes is
> incorrect, since that only is correct inside Lisp strings.  I looked
> at the Elisp manual and the convention seems consistently to be that
> if you write a regexp in non-Lisp syntax, you use @samp, but if you
> write a regexp in Lisp syntax, you use @code and definitely use the
> double quotes.

...with three exceptions in strings.texi and text.texi. A quick grep in
the Elisp manual didn't reveal any @samp{.*} (without quotes) that
looked like they might be a variable's value.

>                 That will still produce `"...."' in Info, but _not_ in
> the printed manual.

That would be preferable.

In (texinfo) code:

      Thus, you should use `@code' for an expression in a program, for the
    name of a variable or function used in a program, or for a keyword in a
    programming language.

If we are in agreement, this paragraph should be amended to say "for the
name *or value* of a variable or function" since it would be
inconsistent and complicate usage to use @code for string values and
@samp for other values.

If the customize rendering of a variable has user-friendly variants of
the variable's values, then those user-friendly variants should perhaps
be rendered in @code for good looks and consistency as well. For
example:

    (defcustom mh-alias-insertion-location 'sorted
      "Specifies where new aliases are entered in alias files.

    This option is set to \"Alphabetical\" by default. If you organize
    your alias file in other ways, then adding aliases to the \"Top\"
    or \"Bottom\" of your alias file might be more appropriate."
      :type '(choice (const :tag "Alphabetical" sorted)
		     (const :tag "Top" top)
		     (const :tag "Bottom" bottom))
      :group 'mh-alias)

We'd use @code{'sorted} and @code{Alphabetical}.

I just changed a handful of @samps to @codes in the manual for these
user-friendly values, and I have to say it looks MUCH better in the
HTML and PDF outputs (no change in info, of course). So, I'd be very
happy to have the convention that any variable's value gets @code.

If we are in agreement, can someone who has the Texinfo manual checked
out make the clarification in the @code section?

Thanks again for your valuable input, Luc.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.


-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642