groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] [PATCH] groff_man.7: Doc how to get >1 paragraphs under one


From: Ingo Schwarze
Subject: Re: [Groff] [PATCH] groff_man.7: Doc how to get >1 paragraphs under one tag
Date: Tue, 16 May 2017 18:02:23 +0200
User-agent: Mutt/1.6.2 (2016-07-01)

Hi Branden,

i think this patch improves the manual page.
See inline for some nits.

Yours,
  Ingo


G. Branden Robinson wrote on Tue, May 16, 2017 at 04:11:09AM -0400:

> Note how to get >1 paragraphs under one tag.
> 
> I have seen many creative ways of getting this wrong, including blank
> input lines.

I tend to just use .sp, but you are probably right that .IP without
arguments is cleaner.


[...]
> diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
> index 2007bbbf..4468359a 100644
> --- a/tmac/groff_man.7.man
> +++ b/tmac/groff_man.7.man
> @@ -347,9 +347,16 @@ or
>  .B .HP
>  (or to the default value if none of them have been used yet).
>  .
> -Font size and face of the paragraph (but not the designator) are reset
> -to its default values.
> +The font size and face of the paragraph (but not the designator) are
> +reset to their default values.

Sure.


>  .
> +.IP
> +Use
> +.B IP
> +without arguments if you simply need a new paragraph at the existing
> +indentation value; for instance, to continue a multi-paragraph
> +discussion after a paragraph tagged with
> +.BR .TP .

That's a very helpful addition.


>  .
>  .IP
>  To start an indented paragraph with a particular indentation but
> @@ -377,18 +384,26 @@ package to format lists.
>  .
>  .
>  .IP \(bu 4
> -.B HP
> +.B TP
>  is another.
>  .
> -This macro produces a paragraph with a left hanging indentation.
> +This macro produces an unindented label followed by an indented
> +paragraph.
>  .
>  .
>  .IP \(bu 4
> -.B TP
> +.B HP
>  is another.
>  .
> -This macro produces an unindented label followed by an indented
> -paragraph.
> +This macro produces a paragraph with a left hanging indentation.
> +.
> +.IP
> +As noted above, use of the
> +.B HP
> +macro is deprecated as being presentation-level.
> +(This paragraph was started with
> +.B .IP
> +with no arguments.)
>  .RE
[...]

All this is merely an example, and it is of excessive length for an
example in the first place.  So i would suggest to simply delete
the middle paragraph about .HP without replacement, and maybe also
delete the "three" from the .IP entry if it bothers you after the
deletion.  Examples should be concise and not repeat unrelated
content discussed elsewhere.

In general, i think examples ought to display source code, *not*
the result when formatted.  As it stands, the example still keeps
you guessing what the source code might look like.  If you show
the source code instead, everyone can easily run it through nroff
and look at how it gets formatted.  But that would be an unrelated
change.

Again, these are just nits, your changes make the page better in
any case.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]