[issue1020] hgrc.5.txt has broken formatting; how to fix?

[Peter Arrenbrecht]

New submission from Peter Arrenbrecht <peter.arrenbrecht at gmail.com>:

There's an annoying formatting problem in hgrc.5.txt, to do with the nested
callout lists in the topic about config sections. Here's an excerpt:

==========
decode/encode::
  Filters for transforming files on checkout/checkin. This would
  typically be used for newline processing or other
  localization/canonicalization of files.

  Filters consist of a filter pattern followed by a filter command.
  Filter patterns are globs by default, rooted at the repository
  root.  For example, to match any file ending in ".txt" in the root
  directory only, use the pattern "\*.txt".  To match any file ending
  in ".c" anywhere in the repository, use the pattern "\*\*.c".

  The filter command can start with a specifier, either "pipe:" or
  "tempfile:".  If no specifier is given, "pipe:" is used by default.

  ...
==========

The idea is obviously that all the indented paragraphs should be part of the
indented block. However, that is not how asciidoc works. Currently, all but the
first indented paragraph are treated as literal examples and are thus not
reflowed. Worse, if there is additional formatting in them, like sub-lists, they
are not formatted at all, so users get to see asciidoc list markup.

To make this work, we would have to write:

==========
decode/encode::
Filters for transforming files on checkout/checkin. This would
typically be used for newline processing or other
localization/canonicalization of files.
+
Filters consist of a filter pattern followed by a filter command.
Filter patterns are globs by default, rooted at the repository
root.  For example, to match any file ending in ".txt" in the root
directory only, use the pattern "\*.txt".  To match any file ending
in ".c" anywhere in the repository, use the pattern "\*\*.c".
+
The filter command can start with a specifier, either "pipe:" or
"tempfile:".  If no specifier is given, "pipe:" is used by default.
+
...
==========

Obviously ugly. And it still does not cover everything. Further below, there is:

==========
hooks::
Commands or Python functions that get automatically executed by
various actions such as starting or finishing a commit. Multiple
hooks can be run for the same action by appending a suffix to the
action. Overriding a site-wide hook can be done by changing its
value or setting it to an empty string.
+
...
+
Most hooks are run with environment variables set that give added
useful information.  For each hook below, the environment variables
it is passed are listed with names of the form "$HG_foo".
+
  changegroup;;
    Run after a changegroup has been added via push, pull or
    unbundle. ID of the first new changeset is in $HG_NODE.  URL from
    which changes came is in $HG_URL.
  ...
  update;;
    Run after updating the working directory.  Changeset ID of first
    new parent is in $HG_PARENT1.  If merge, ID of second new parent
    is in $HG_PARENT2.  If update succeeded, $HG_ERROR=0.  If update
    failed (e.g. because conflicts not resolved), $HG_ERROR=1.
+
Note: it is generally better to use standard hooks rather than the
generic pre- and post- command hooks as they are guaranteed to be
called in the appropriate contexts for influencing transactions.
Also, hooks like "commit" will be called in all contexts that
generate a commit (eg. tag) and not just the commit command.
+
...
==========

The idea here is that the note at the end should be at the indentation level of
the main text about hooks again. However, asciidoc considers it a continuation
of "update" and indents it twice.

One idea to improve all this might be to switch to:

==========
.decode/encode
Filters for transforming files on checkout/checkin. This would
typically be used for newline processing or other
localization/canonicalization of files.

Filters consist of a filter pattern followed by a filter command.
Filter patterns are globs by default, rooted at the repository
root.  For example, to match any file ending in ".txt" in the root
directory only, use the pattern "\*.txt".  To match any file ending
in ".c" anywhere in the repository, use the pattern "\*\*.c".
==========

This means that the text is no longer indented in the output. Instead, we get
bold inlined subtitles, as in the following (*..* denotes bold face):

*decode/encode*.  Filters for transforming...

While this does make authoring easier, I think it's less scannable for users.

----------
assignedto: parren
messages: 5469
nosy: parren
priority: bug
status: chatting
title: hgrc.5.txt has broken formatting; how to fix?
topic: documentation

____________________________________________________
Mercurial issue tracker <mercurial-bugs at selenic.com>
<http://www.selenic.com/mercurial/bts/issue1020>
____________________________________________________