MH-E manual update

MH-E manual update

[Bill Wohler]

Bill Wohler <wohler@newt.com> wrote:

> I'll update the MH-E manual accordingly.

The existing manual in Emacs is for an *ancient* version 5 of MH-E. For
the past two years (!) I've been rewriting the manual which started as
three chapters in the O'Reilly MH book to be more like other Emacs
manuals. I've also been adding new chapters for all of the new features
that we've added in the past five years.

It's sort of a race to see if I can finish the job and release MH-E 8.0
with it before Emacs 22 is released. The good (?) news is that I got
laid off a while back and am committed to work on the manual full time
and finish it before looking for another job.

I certainly do not want to hold up the release for the inclusion of this
manual, but it would be nice to get a heads-up when someone gets close
to cutting tarballs. While the manual is still missing a few chapters,
it is close enough to being in a state where releasing the manual as is
would still benefit the community.

Thanks.

-- 
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: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click

Re: MH-E manual update

[Eli Zaretskii]

> Date: Thu, 08 Dec 2005 16:27:11 -0800
> From: Bill Wohler <wohler@newt.com>
> Cc: mh-e-devel@lists.sourceforge.net
> 
> The existing manual in Emacs is for an *ancient* version 5 of MH-E. For
> the past two years (!) I've been rewriting the manual which started as
> three chapters in the O'Reilly MH book

Uh-oh...  If those chapters started as part of O'Reilly's book, are
you sure they can be released under GFDL?

> It's sort of a race to see if I can finish the job and release MH-E 8.0
> with it before Emacs 22 is released.

I don't have the slightest doubt that you will beat Emacs to it :-(

> it would be nice to get a heads-up when someone gets close to
> cutting tarballs.

Your heads-up will be when you hear about start of the pretest cycle,
at which point I expect emacs-22.0.50.tar.gz to hit alpha.gnu.org.
The pretest should take a while, with new pretest tarballs uploaded
from time to time, which should give you enough time to catch up.

Re: MH-E manual update

[Bill Wohler]

Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Bill Wohler <wohler@newt.com>
> > 
> > The existing manual in Emacs is for an *ancient* version 5 of MH-E. For
> > the past two years (!) I've been rewriting the manual which started as
> > three chapters in the O'Reilly MH book
> 
> Uh-oh...  If those chapters started as part of O'Reilly's book, are
> you sure they can be released under GFDL?

Yes. O'Reilly released them under the GPL:

  http://www.ics.uci.edu/~mh/book/

We had a discussion a while back about dual-licensing the manual since
it needs to be released under the GFDL for Emacs and under the GPL for
Debian (per the DFSG). If that's still the case, it would be helpful if
someone could point out an example of this so that I could see the
mechanism (i.e., text) of how this is actually done.

Would adding a mention of MH-E 8.0 source and manual be appropriate for
the FOR-RELEASE file?

-- 
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: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click

Re: MH-E manual update

[Eli Zaretskii]

> cc: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net
> Date: Fri, 09 Dec 2005 06:40:51 -0800
> From: Bill Wohler <wohler@newt.com>
> 
> Would adding a mention of MH-E 8.0 source and manual be appropriate for
> the FOR-RELEASE file?

Yes, I think so.  But please wait for Richard to give the definitive
answer.


-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click

Re: MH-E manual update

[Richard M. Stallman]

    Uh-oh...  If those chapters started as part of O'Reilly's book, are
    you sure they can be released under GFDL?

The only relevant question is who has the copyright
and what the copyright holder will permit.
Chances are I already discussed this with Bill Wohler and
don't remember, but if not, I'll do so when necessary.

Re: MH-E manual update

[Bill Wohler]

Richard M. Stallman <rms@gnu.org> wrote:

>     Uh-oh...  If those chapters started as part of O'Reilly's book, are
>     you sure they can be released under GFDL?
> 
> The only relevant question is who has the copyright
> and what the copyright holder will permit.
> Chances are I already discussed this with Bill Wohler and
> don't remember, but if not, I'll do so when necessary.

The chapters of the O'Reilly book were written with an agreement that
they would carry the GPL and appear in Emacs with the FSF as copyright
holder. If you look in the Emacs source, you'll see that is already the
case. All of the MH-E contributors have signed papers with the FSF. No
problem there.

The problem is with the licensing.

Unfortunately, the manual (in the Emacs repository) was later switched
to the GFDL by the Emacs maintainers and this has caused major problems.
The biggest is that the two licenses are incompatible which is a problem
because the docstrings in the code are cut and pasted into the manual
and vice-versa. Another problem is that the manual is not only found in
Emacs. It appears in Debian (which has deemed that the GFDL is too
restrictive for them) and in the online MH book
(http://www.ics.uci.edu/~mh/book/) which carries the GPL.

One solution was to relicense the manual under the GPL, but I don't
think is is acceptable to Richard.

Another solution was to rewrite the GFDL so that it was compatible with
the GPL and acceptable by Debian, but I don't think that has been done
either.

Failing those two solutions, one suggestion that was proposed by
Dave Turner <licensing@fsf.org> was to use a dual-license scheme and
license the manual under both the GPL and GFDL.

Would that be acceptable to all parties?

-- 
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: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click

Re: MH-E manual update

[Richard M. Stallman]

    The biggest is that the two licenses are incompatible which is a problem
    because the docstrings in the code are cut and pasted into the manual
    and vice-versa.

That is not a legal problem, since the FSF is the copyright holder for
both.  However, the use of doc strings in the manual without extensive
rewriting would tend to make the manual less than ideal.  Doc strings
and a manual are rather different, and the text that is good for one
is not very good for the other.

    Another solution was to rewrite the GFDL so that it was compatible with
    the GPL and acceptable by Debian, but I don't think that has been done
    either.

This idea sounds nice, but it makes no sense.  The GFDL can't be made
compatible with the GPL except by eliminating it.  I hope no one ever
said that we would do this.

    Failing those two solutions, one suggestion that was proposed by
    Dave Turner <licensing@fsf.org> was to use a dual-license scheme and
    license the manual under both the GPL and GFDL.

What we want to do is release it solely under the GFDL.
That is our policy for licensing GNU manuals.
Debian should interpret its criteria in a more sensible way
and use it under the GFDL.

Re: MH-E manual update

[Bill Wohler]

I am pleased to announce that I've just moved the primary CVS
repository of the MH-E manual from SourceForge to Savannah (this had
been done for the source a while ago). This action updated the
existing, ancient, Edition 1.3 of the manual for MH-E 5.0.2, to
version 7.93 corresponding with MH-E 7.93, the fourth 8.0 beta.

I'd appreciate it if someone could take a quick look and ensure it
(man/mh-e.texi) meets Emacs' standards. It does produce wonderful HTML
and PDF output (see http://mh-e.sourceforge.net/manual/) and compiles
without error or overfull hboxes. It also went from 63 to 140 pages
(US Letter).

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

Re: MH-E manual update

[Eli Zaretskii]

> From: Bill Wohler <wohler@newt.com>
> Date: Mon, 06 Mar 2006 17:29:49 -0800
> Cc: mh-e-devel@lists.sourceforge.net
> 
> I'd appreciate it if someone could take a quick look and ensure it
> (man/mh-e.texi) meets Emacs' standards.

Well, it's over 9000 lines, so it's beyond my resources to read it in
its entirety and give you feedback on every sentence.  Some comments
based on casual reading are below:

In general, the manual seems to be well designed and well written.

The GNU documentation standards call for 2 spaces after a period that
ends a sentence; this manual leaves only one space.

This paragraph has an extraneous quote character at its end:

    The second extra option is @code{mh-xemacs-tool-bar-position} which
    controls the placement of the tool bar along the four edges of the
    frame. You can choose from one of @samp{Same As Default Tool Bar},
    @samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this
    variable is set to anything other than @samp{Same As Default Tool Bar}
    and the default tool bar is in a different location, then two tool
    bars will be displayed: the MH-E tool bar and the default tool bar."

This paragraph uses ".." in plain text; you should use ``..'' instead,
as the latter produces a nicer output in PDF and DVI.

    First, run @samp{spamassassin -t} on every mail message in your
    archive and use @command{gnumeric} to verify that the average plus the
    standard deviation of good mail is under 5, the SpamAssassin default
    for "spam".

The text uses @samp{"foo"} when it describes values that are strings.
Here's one of many examples, with the offending @samp marked by <<<<:

    @item mh-scan-body-regexp
    This regular expression matches the message body fragment. Note that
    the default setting of @code{mh-folder-font-lock-keywords} expects
    this expression to contain at least one parenthesized expression which
    matches the body text as in the default of
    @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.

Some indexing commands need work, IMHO.  Here's one example:

    @cindex Emacs, mark
    @cindex Emacs, point
    @cindex Emacs, region

It is not useful to have several index entries all starting with the
same string and pointing to the same page.  I'd change this to

    @cindex Emacs mark, point and region

Actually, it might be better yet to reverse the parts of the index
entries for the individual terms:

    @cindex mark, in Emacs
    @cindex point, in Emacs
    @cindex region, in Emacs

and then you can discard the entries without ", in Emacs" altogether.

Here's another similar example:

    @cindex @samp{Draft-Folder:} MH profile component
    @cindex @samp{Path:} MH profile component
    @cindex @samp{Previous-Sequence:} MH profile component
    @cindex @samp{Unseen-Sequence:} MH profile component
    @cindex MH profile component, @samp{Draft-Folder:}
    @cindex MH profile component, @samp{Path:}
    @cindex MH profile component, @samp{Previous-Sequence:}
    @cindex MH profile component, @samp{Unseen-Sequence:}

Again, I'd modify the first 4 slightly, like this:

    @cindex @samp{Draft-Folder:}, MH profile component
    @cindex @samp{Path:}, MH profile component
    @cindex @samp{Previous-Sequence:}, MH profile component
    @cindex @samp{Unseen-Sequence:}, MH profile component

and drop the other 4.

OTOH, I didn't see an index entry that explains what is the ``MH
profile'' and how to set it up.

So I suggest to review all your index entries to remove the unhelpful
ones.

Here's incorrect use of @ref:

    The text usually says to turn on an option by setting it to a
    @emph{non-@code{nil}} value, because sometimes values other than
    @samp{on} are meaningful (for example, see @code{mh-mhl-format-file},
    described in @ref{Viewing}).

There should be a period after the right brace that ends the @ref.

Here's another:

    appears in an Emacs buffer whose mode is MH-Letter (see the Figure in
    @ref{Sending Mail Tour} to see what the buffer looks like).

Here, the right brace should be followed by a comma.

Please check all your @ref's, there are some more that lack
punctuation after the right brace.

That's all for now, I hope it helps.

Re: MH-E manual update

[Bill Wohler]

Eli Zaretskii <eliz@gnu.org> wrote:

> This paragraph has an extraneous quote character at its end:

I thought you weren't reading carefully ;-).

Fixed.

> This paragraph uses ".." in plain text; you should use ``..'' instead,
> as the latter produces a nicer output in PDF and DVI.

Fixed.

> The text uses @samp{"foo"} when it describes values that are strings.
> Here's one of many examples, with the offending @samp marked by <<<<:
> 
>     @item mh-scan-body-regexp
>     This regular expression matches the message body fragment. Note that
>     the default setting of @code{mh-folder-font-lock-keywords} expects
>     this expression to contain at least one parenthesized expression which
>     matches the body text as in the default of
>     @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.

Taking a closer look, let's say we had the convention that you use
quotes for string-valued variables. If you look at this example in
(emacs)Mail Aliases, wrapping the value in double quotes would look
really bad.

  @samp{"George W. Bush" <bush@@whitehouse.gov>}.

While the user has to enter the quotes in a setq, they don't in the
customization buffer, so that would be a good argument for removing the
quotes.

OK, I might have talked myself into removing the quotes but I'd like to
first measure the consensus. Looking at the existing strings in the
manual, there doesn't seem to be a clear precedent or convention, but
rather a mix of usage.

What do others think about the addition of literal quotes in a @samp{}
for a string value?

> Some indexing commands need work, IMHO.  Here's one example:
> 
>     @cindex Emacs, mark
>     @cindex Emacs, point
>     @cindex Emacs, region
> 
> It is not useful to have several index entries all starting with the
> same string and pointing to the same page.  I'd change this to
> 
>     @cindex Emacs mark, point and region
> 
> Actually, it might be better yet to reverse the parts of the index
> entries for the individual terms:
> 
>     @cindex mark, in Emacs
>     @cindex point, in Emacs
>     @cindex region, in Emacs
> 
> and then you can discard the entries without ", in Emacs" altogether.

I disagree. You can't look at this example in isolation. If you're in
the index with a lot of other "Emacs" entries, you might not find the
"region" entry using your suggested entry since it would sorted under
"m".

> Here's another similar example:
> 
>     @cindex @samp{Draft-Folder:} MH profile component
>     @cindex @samp{Path:} MH profile component
>     @cindex @samp{Previous-Sequence:} MH profile component
>     @cindex @samp{Unseen-Sequence:} MH profile component
>     @cindex MH profile component, @samp{Draft-Folder:}
>     @cindex MH profile component, @samp{Path:}
>     @cindex MH profile component, @samp{Previous-Sequence:}
>     @cindex MH profile component, @samp{Unseen-Sequence:}
> 
> Again, I'd modify the first 4 slightly, like this:
> 
>     @cindex @samp{Draft-Folder:}, MH profile component
>     @cindex @samp{Path:}, MH profile component
>     @cindex @samp{Previous-Sequence:}, MH profile component
>     @cindex @samp{Unseen-Sequence:}, MH profile component
> 
> and drop the other 4.

I disagree, but for a different reason. The user might know that he's
looking for an "MH profile component" but can't quite remember the name.
This indexing technique provides a nice quick-reference table.

> OTOH, I didn't see an index entry that explains what is the ``MH
> profile'' and how to set it up.

Fixed.

> So I suggest to review all your index entries to remove the unhelpful
> ones.

In the old days, when makeinfo dutifully indexed every entry, a good
convention was to take care to have one index entry per node per item.
The problem with that is that when you move paragraphs around, you might
either "steal" an index entry from a node, or "forget" to add a new
entry in the new node.

Now makeinfo ensures there is only entry per node so I thought it would
be a good idea to add appropriate index entries to each paragraph,
independent of the context. That way, if you move the paragraph, the
index entries go with it. Thoughts?

> Here's incorrect use of @ref:
> 
>     The text usually says to turn on an option by setting it to a
>     @emph{non-@code{nil}} value, because sometimes values other than
>     @samp{on} are meaningful (for example, see @code{mh-mhl-format-file},
>     described in @ref{Viewing}).
> 
> There should be a period after the right brace that ends the @ref.
> 
> Here's another:
> 
>     appears in an Emacs buffer whose mode is MH-Letter (see the Figure in
>     @ref{Sending Mail Tour} to see what the buffer looks like).
> 
> Here, the right brace should be followed by a comma.
> 
> Please check all your @ref's, there are some more that lack
> punctuation after the right brace.

Thanks. I fixed a handful of them.

Question: Cross-references with five arguments are preceded by
"section" in printed output (texi2pdf), but not in info output. Where
there is a URL to the same document, I insert a @uref in @ifhtml. I've
been inserting the word "section" before the @uref to be consistent with
the printed manual, but now I'm thinking I should just drop the word
"section" to be consistent with Info and let @uref do what it wants to
do. Thoughts?

> That's all for now, I hope it helps.

Great feedback, Eli, thanks!

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

Re: MH-E manual update

[Luc Teirlinck]

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.  That will still produce `"...."' in Info, but _not_ in
the printed manual.  (I noticed that I recently violated parts of that
convention myself, but that is corrected now.)

Sincerely,

Luc.

Re: MH-E manual update

[Bill Wohler]

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

Re: MH-E manual update

[Luc Teirlinck]

Bill Wohler wrote:

   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.

It already says: "you should use `@code' for an expression in a program".
Strings in a program are expressions, be it constant ones.  One writes:
"The standard value of this variable is @code{nil}", not @samp{nil}.

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

I changed those three to use @code, since they were inconsistent with
the vast majority of similar cases.

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

Karl Berry maintains that manual, but I am not immediately sure that a
change is called for, for the reasons explained above.

Sincerely,

Luc.

Re: MH-E manual update

[Bill Wohler]

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

> Bill Wohler wrote:
> 
>    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.
> 
> It already says: "you should use `@code' for an expression in a program".
> Strings in a program are expressions, be it constant ones.  One writes:
> "The standard value of this variable is @code{nil}", not @samp{nil}.
> 
>    ...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.
> 
> I changed those three to use @code, since they were inconsistent with
> the vast majority of similar cases.
> 
>    If we are in agreement, can someone who has the Texinfo manual checked
>    out make the clarification in the @code section?
> 
> Karl Berry maintains that manual, but I am not immediately sure that a
> change is called for, for the reasons explained above.

Agreed. I'll fix these in the MH-E manual.

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

Re: MH-E manual update

[Luc Teirlinck]

Bill Wohler wrote:

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

If you are going to include the entire defcustom, you would obviously
use @example.  But if you then refer to Alphabetical outside of the
@example, things get subtle.  I believe that if you refer to the
string "Alphabetical", which the programmer has to write in his
defcustom, you use @code.  However, if you refer to the text that
actually appears in the Custom buffer, you use @samp.

That is why you have @samp in the following quote from
lispref/customize.texi:

  @example
  (choice (integer :tag "Number of spaces")
	  (string :tag "Literal text"))
  @end example

  @noindent
  so that the menu offers @samp{Number of spaces} and @samp{Literal text}.

It talks about the text in the menu, as opposed to the strings in the code.

Sincerely,

Luc.

Re: MH-E manual update

[Bill Wohler]

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

>                But if you then refer to Alphabetical outside of the
> @example, things get subtle.

Right, hence my suggestion just to use @code always. To avoid the
subtleties.

> That is why you have @samp in the following quote from
> lispref/customize.texi:
> 
>   @example
>   (choice (integer :tag "Number of spaces")
> 	  (string :tag "Literal text"))
>   @end example
> 
>   @noindent
>   so that the menu offers @samp{Number of spaces} and @samp{Literal text}.

OK, I'll leave my menu items in @samp. But, they do look *really* good
in @code.

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

Re: MH-E manual update

[Luc Teirlinck]

Bill Wohler wrote:

   >   @noindent
   >   so that the menu offers @samp{Number of spaces} and @samp{Literal text}.

   OK, I'll leave my menu items in @samp. But, they do look *really* good
   in @code.

Just to make sure: without double quotes here, as the example shows.
So you do not have that problem here.

Sincerely,

Luc.

Re: MH-E manual update

[Bill Wohler]

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

> Bill Wohler wrote:
> 
>    >   @noindent
>    >   so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
> 
>    OK, I'll leave my menu items in @samp. But, they do look *really* good
>    in @code.
> 
> Just to make sure: without double quotes here, as the example shows.
> So you do not have that problem here.

That's correct. Just the actual expressions, including those strings,
will be changed to @code. The menu item or user-friendly rendering will
remain @samp (unless folks decide to change this, in which I would be in
agreement ;-).

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

Re: MH-E manual update

[Luc Teirlinck]

>From mh-e.texi:

  Use @samp{M-x apropos @key{RET} mh-scan.*regexp @key{RET}} to obtain a
  list of these variables.

That looks very much like a literal sequence of characters for a user
to type.  In that case, it should be @kbd instead of @samp.

Sincerely,

Luc.

Re: MH-E manual update

[Bill Wohler]

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

>>From mh-e.texi:
>
>   Use @samp{M-x apropos @key{RET} mh-scan.*regexp @key{RET}} to obtain a
>   list of these variables.
>
> That looks very much like a literal sequence of characters for a user
> to type.  In that case, it should be @kbd instead of @samp.

Right you are. Fixed. Thanks!

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

Re: MH-E manual update

[Luc Teirlinck]

Bill Wohler wrote:

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

   >                But if you then refer to Alphabetical outside of the
   > @example, things get subtle.

   Right, hence my suggestion just to use @code always. To avoid the
   subtleties.

@code is meant for code.  The strings in the defcustom are code and
text in a Custom buffer or menu is not.  If you just look at
"Alphabetical", there does not seem to be too much of a difference.
But your defcustom could contain, say,

   :tag "\\1\\"

In that case, the code in the defcustom gets referred to as
@code{"\\1\\"} and what appears in the menu is @samp{\1\}.
The first is the string as it needs to be written in a program,
the second the actual string as it appears in the menu and the two are
not the same.

Sincerely,

Luc.

Re: MH-E manual update

[Eli Zaretskii]

> cc: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net
> Comments: In-reply-to Eli Zaretskii <eliz@gnu.org>
>    message dated "Sat, 11 Mar 2006 16:30:14 +0200."
> Date: Sat, 11 Mar 2006 12:08:10 -0800
> From: Bill Wohler <wohler@newt.com>
> 
> > Some indexing commands need work, IMHO.  Here's one example:
> > 
> >     @cindex Emacs, mark
> >     @cindex Emacs, point
> >     @cindex Emacs, region
> > 
> > It is not useful to have several index entries all starting with the
> > same string and pointing to the same page.  I'd change this to
> > 
> >     @cindex Emacs mark, point and region
> > 
> > Actually, it might be better yet to reverse the parts of the index
> > entries for the individual terms:
> > 
> >     @cindex mark, in Emacs
> >     @cindex point, in Emacs
> >     @cindex region, in Emacs
> > 
> > and then you can discard the entries without ", in Emacs" altogether.
> 
> I disagree. You can't look at this example in isolation. If you're in
> the index with a lot of other "Emacs" entries, you might not find the
> "region" entry using your suggested entry since it would sorted under
> "m".

Sorry, I don't understand.  My last suggestion was to remove the
entries that begin with "Emacs, " altogether, so how are the other
"Emacs" entries relevant?

Anyway, it sounds like you are thinking about a user who looks at the
printed version, while I think about someone who looks at the on-line
Info version.  In the latter case, typing "i Emacs RET" will
(eventually) get us to the above entries as well, so nothing is lost.
OTOH, with your entries, typing "i Emacs TAB" will show a very long list
of entries, which is not too good, I think.  In particular, a reader
who wants to find the description of point is more likely to type
"i point TAB" or "i point RET" than "i Emacs, point".

> > Here's another similar example:
> > 
> >     @cindex @samp{Draft-Folder:} MH profile component
> >     @cindex @samp{Path:} MH profile component
> >     @cindex @samp{Previous-Sequence:} MH profile component
> >     @cindex @samp{Unseen-Sequence:} MH profile component
> >     @cindex MH profile component, @samp{Draft-Folder:}
> >     @cindex MH profile component, @samp{Path:}
> >     @cindex MH profile component, @samp{Previous-Sequence:}
> >     @cindex MH profile component, @samp{Unseen-Sequence:}
> > 
> > Again, I'd modify the first 4 slightly, like this:
> > 
> >     @cindex @samp{Draft-Folder:}, MH profile component
> >     @cindex @samp{Path:}, MH profile component
> >     @cindex @samp{Previous-Sequence:}, MH profile component
> >     @cindex @samp{Unseen-Sequence:}, MH profile component
> > 
> > and drop the other 4.
> 
> I disagree, but for a different reason. The user might know that he's
> looking for an "MH profile component" but can't quite remember the name.

That's why I suggested an entry for "MH profile component".  With that
problem out of your way, you don't need this redundancy.

> This indexing technique provides a nice quick-reference table.

Index is not the proper vehicle for quick-reference tables.  If you
want a quick reference, add a short section that summarizes these
commands/options, and have an index entry that points to it:

  @cindex MH profile components, quick reference

> Now makeinfo ensures there is only entry per node

?? Perhaps there's a Texinfo feature I'm not aware of--could you show
this at work?

> so I thought it would
> be a good idea to add appropriate index entries to each paragraph,
> independent of the context. That way, if you move the paragraph, the
> index entries go with it. Thoughts?

I didn't suggest to limit yourself to a single entry per node.  I
suggested not to have several entries that coincide in too many
initial characters.  The reason is that it makes TAB-completion less
efficient in the `i' command.  The `i' command is the key to using the
manual as a reference, so anything that gets in the way of it is
annoying when you just need to find that one piece of information.

> Question: Cross-references with five arguments are preceded by
> "section" in printed output (texi2pdf), but not in info output. Where
> there is a URL to the same document, I insert a @uref in @ifhtml. I've
> been inserting the word "section" before the @uref to be consistent with
> the printed manual, but now I'm thinking I should just drop the word
> "section" to be consistent with Info and let @uref do what it wants to
> do. Thoughts?

I agree that dropping the "section" part is a good idea.

Re: MH-E manual update

[Bill Wohler]

Eli Zaretskii <eliz@gnu.org> wrote:

> > cc: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net
> > Comments: In-reply-to Eli Zaretskii <eliz@gnu.org>
> >    message dated "Sat, 11 Mar 2006 16:30:14 +0200."
> > Date: Sat, 11 Mar 2006 12:08:10 -0800
> > From: Bill Wohler <wohler@newt.com>
> > 
> > > Some indexing commands need work, IMHO.  Here's one example:
> > > 
> > >     @cindex Emacs, mark
> > >     @cindex Emacs, point
> > >     @cindex Emacs, region
> > > 
> > > It is not useful to have several index entries all starting with the
> > > same string and pointing to the same page.  I'd change this to
> > > 
> > >     @cindex Emacs mark, point and region
> > > 
> > > Actually, it might be better yet to reverse the parts of the index
> > > entries for the individual terms:
> > > 
> > >     @cindex mark, in Emacs
> > >     @cindex point, in Emacs
> > >     @cindex region, in Emacs
> > > 
> > > and then you can discard the entries without ", in Emacs" altogether.
> > 
> > I disagree. You can't look at this example in isolation. If you're in
> > the index with a lot of other "Emacs" entries, you might not find the
> > "region" entry using your suggested entry since it would sorted under
> > "m".
> 
> Sorry, I don't understand.  My last suggestion was to remove the
> entries that begin with "Emacs, " altogether, so how are the other
> "Emacs" entries relevant?
> 
> Anyway, it sounds like you are thinking about a user who looks at the
> printed version, while I think about someone who looks at the on-line
> Info version.

WOW! I never knew about the `i' command. That's awesome! Yes, since I
never knew about the `i' command, I was thinking about the user looking
at the index directly, whether it be in Info or HTML or PDF.

> OTOH, with your entries, typing "i Emacs TAB" will show a very long list
> of entries, which is not too good, I think.

I think it's WONDERFUL!

>                                              In particular, a reader
> who wants to find the description of point is more likely to type
> "i point TAB" or "i point RET" than "i Emacs, point".

Since the audience of the MH-E user includes someone who does not
know Emacs (see Info node (mh-e) Preface), having an index section that
starts with Emacs, is useful since they might not remember the term
"point" but would know that it is an Emacs' thingy.

Don't laugh. *I* used MH-E before I used Emacs. This was in 1985.

> > > Here's another similar example:
> > > 
> > >     @cindex @samp{Draft-Folder:} MH profile component
> > >     @cindex @samp{Path:} MH profile component
> > >     @cindex @samp{Previous-Sequence:} MH profile component
> > >     @cindex @samp{Unseen-Sequence:} MH profile component
> > >     @cindex MH profile component, @samp{Draft-Folder:}
> > >     @cindex MH profile component, @samp{Path:}
> > >     @cindex MH profile component, @samp{Previous-Sequence:}
> > >     @cindex MH profile component, @samp{Unseen-Sequence:}
> > > 
> > > Again, I'd modify the first 4 slightly, like this:
> > > 
> > >     @cindex @samp{Draft-Folder:}, MH profile component
> > >     @cindex @samp{Path:}, MH profile component
> > >     @cindex @samp{Previous-Sequence:}, MH profile component
> > >     @cindex @samp{Unseen-Sequence:}, MH profile component
> > > 
> > > and drop the other 4.
> > 
> > I disagree, but for a different reason. The user might know that he's
> > looking for an "MH profile component" but can't quite remember the name.
> 
> That's why I suggested an entry for "MH profile component".  With that
> problem out of your way, you don't need this redundancy.
> 
> > This indexing technique provides a nice quick-reference table.
> 
> Index is not the proper vehicle for quick-reference tables.  If you
> want a quick reference, add a short section that summarizes these
> commands/options...

...which needs to be updated manually and easily gets out of date.
No, thanks.

>   @cindex MH profile components, quick reference
> 
> > Now makeinfo ensures there is only entry per node
> 
> ?? Perhaps there's a Texinfo feature I'm not aware of--could you show
> this at work?

Just to double-check what I think I once saw, I added two index entries
"@cindex foo" in a node and ran makeinfo (version 4.8) and texi2pdf
(version (GNU Texinfo 4.8) 1.34), and noted that there was only one
entry in each of the info, HTML, and PDF indexes. Try it!

> > so I thought it would
> > be a good idea to add appropriate index entries to each paragraph,
> > independent of the context. That way, if you move the paragraph, the
> > index entries go with it. Thoughts?
> 
> I didn't suggest to limit yourself to a single entry per node.
> ...

My question was independent of your suggestions. It's something I've
been thinking about for some time. Sorry if that wasn't clear.

Let's say I have two paragraphs in a chapter that mention
`image-load-path'. Conventional wisdom puts the "@vindex
image-load-path" entry before the first paragraph that mentions it. The
problem with this is that when I later move the first paragraph with
index entry to another node, the old node now lacks an index entry. Or,
if I were to move the second paragraph to another node, the new node now
lacks an index entry. By just always adding an index entry, you save
time in asking yourself if you need an index entry or not in the first
place (just add it), and you eliminate the chance that the editor will
forget to update the index appropriately.

> > Question: Cross-references with five arguments are preceded by
> > "section" in printed output (texi2pdf), but not in info output. Where
> > there is a URL to the same document, I insert a @uref in @ifhtml. I've
> > been inserting the word "section" before the @uref to be consistent with
> > the printed manual, but now I'm thinking I should just drop the word
> > "section" to be consistent with Info and let @uref do what it wants to
> > do. Thoughts?
> 
> I agree that dropping the "section" part is a good idea.

Thanks for the feedback!

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

Re: MH-E manual update

[Robert J. Chassell]

    Since the audience of the MH-E user includes someone who does not
    know Emacs (see Info node (mh-e) Preface), having an index section
    that starts with Emacs, is useful since they might not remember
    the term "point" but would know that it is an Emacs' thingy.

As (texinfo)Index Entries says,

    When you are making index entries, it is good practice to think of
    the different ways people may look for something.  Different
    people _do not_ think of the same words when they look something
    up.  A helpful index will have items indexed under all the
    different words that people may use.

Please make entries both with and without the `Emacs' prefix.  People
who use `i' may be taken to the Emacs entry first.

But certainly many hardcopy readers are likely first to look under
`Emacs, mark, point, and region' although not all.  Some will look
under `mark' first.  

And, if those who use `Info-index' look for `mark', `point', or
`region', rather than `Emacs, ...', they will be taken to those
entries.

As (texinfo)Index Entries also says,

    A good index will have both entries and will help both readers.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: MH-E manual update

[Richard Stallman]

It is not useful for a manual about Emacs to give lots of index entries
a variant form that starts with "Emacs".  That would bloat the index
without being very useful.


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

Re: MH-E manual update

[Robert J. Chassell]

   It is not useful for a manual about Emacs to give lots of index entries
   a variant form that starts with "Emacs".  That would bloat the index
   without being very useful.

But for a separate MH-E manual, a couple of entries are useful for
people who have not started using Emacs.  The entries certainly do not
fit in an Emacs manual. (As far as I can see, one additional entry for
`mail interface, MH' ought to complement the existing existing entry
for `MH mail interface').

(In the existing MH-E manual index, the twenty-eight entries in which
Emacs is the first word are far too many, whether the document is
printed or read on line.)

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: MH-E manual update

[Bill Wohler]

Richard Stallman <rms@gnu.org> wrote:

> It is not useful for a manual about Emacs to give lots of index entries
> a variant form that starts with "Emacs".  That would bloat the index
> without being very useful.

Agreed. But that is irrelevant here. MH-E is not a manual about Emacs.
It is a manual about MH-E. And it is not contained within the Emacs
manual. And we are only talking about fewer than 30 entries in an index
with nearly 2000 entries anyway, so it doesn't bloat the index and most
important, it is useful.

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

Re: MH-E manual update

[Eli Zaretskii]

> Comments: In-reply-to Richard Stallman <rms@gnu.org>
> 	message dated "Mon, 13 Mar 2006 07:55:24 -0500."
> Date: Mon, 13 Mar 2006 08:29:41 -0800
> From: Bill Wohler <wohler@newt.com>
> Cc: bob@rattlesnake.com, mh-e-devel@lists.sourceforge.net, emacs-devel@gnu.org
> 
> Richard Stallman <rms@gnu.org> wrote:
> 
> > It is not useful for a manual about Emacs to give lots of index entries
> > a variant form that starts with "Emacs".  That would bloat the index
> > without being very useful.
> 
> Agreed. But that is irrelevant here. MH-E is not a manual about Emacs.
> It is a manual about MH-E. And it is not contained within the Emacs
> manual. And we are only talking about fewer than 30 entries in an index
> with nearly 2000 entries anyway, so it doesn't bloat the index and most
> important, it is useful.

It's being useful that I was concerned about when I wrote that.  IMO,
an MH-E users are extremely unlikely to look for information about
Emacs in an MH-E manual.  Therefore, they probably won't type "Emacs"
at the `i's command prompt.  So I expect those 30 entries to be
rarely, if ever, used.