-man "line scope broken"

-man "line scope broken"

[Kristaps Dzonsons]

Hi,

The TODO states:

- bashbug(1) complains "line scope broken" after
   .SM
   .B something
   should either just work or be a warning
   reported by naddy@

I don't understand this.  Why shouldn't it be an error (it's a regular 
error, not a fatal one)?  After all, the `SM' is lost by the subsequent 
`B' (tested under groff -Tps): information is clearly lost.  Changing it 
to a warning is trivial, but I want to be sure that this is meaningful.

Thanks,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: -man "line scope broken"

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Tue, Mar 22, 2011 at 05:05:10PM +0100:

> The TODO states:
> 
> - bashbug(1) complains "line scope broken" after
>   .SM
>   .B something
>   should either just work or be a warning
>   reported by naddy@
> 
> I don't understand this.  Why shouldn't it be an error (it's a
> regular error, not a fatal one)?  After all, the `SM' is lost by the
> subsequent `B' (tested under groff -Tps): information is clearly
> lost.

What i meant when writing "... but typically, preparing that output
involves information loss, ..." in mandoc(1) was _significant_
information loss, i.e. loss of information that the manual author
intended to convey to the manual reader, typically loss of a part
of the text of the manual, as opposed to loss of information in a
mathematical sense.  When there is no text to be lost, even if the
information is lost that these zero words should be rendered in
small font, i don't think we need to regard that as significant
information loss.  Even less so given that we don't distinguish
font sizes in terminal output anyway, which is the most important
output mode.

Maybe we can amend the wording in the manual to reduce the risk
of confusion?  But i don't have a good suggestion to improve the
wording right now...

> Changing it to a warning is trivial, but I want to be sure
> that this is meaningful.

In think the description of a warning fits quite well here:

   warning  An input file uses obsolete, discouraged or non-portable
            syntax.  All the same, the meaning of the input is
            unambiguous and a correct rendering can be produced.  

Which is, here, dropping the .SM and rendering "something"
as plain bold.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: -man "line scope broken"

[Kristaps Dzonsons]

>> The TODO states:
>>
>> - bashbug(1) complains "line scope broken" after
>>    .SM
>>    .B something
>>    should either just work or be a warning
>>    reported by naddy@
>>
>> I don't understand this.  Why shouldn't it be an error (it's a
>> regular error, not a fatal one)?  After all, the `SM' is lost by the
>> subsequent `B' (tested under groff -Tps): information is clearly
>> lost.
>
> What i meant when writing "... but typically, preparing that output
> involves information loss, ..." in mandoc(1) was _significant_
> information loss, i.e. loss of information that the manual author
> intended to convey to the manual reader, typically loss of a part
> of the text of the manual, as opposed to loss of information in a
> mathematical sense.  When there is no text to be lost, even if the
> information is lost that these zero words should be rendered in
> small font, i don't think we need to regard that as significant
> information loss.  Even less so given that we don't distinguish
> font sizes in terminal output anyway, which is the most important
> output mode.
>
> Maybe we can amend the wording in the manual to reduce the risk
> of confusion?  But i don't have a good suggestion to improve the
> wording right now...
>
>> Changing it to a warning is trivial, but I want to be sure
>> that this is meaningful.
>
> In think the description of a warning fits quite well here:
>
>     warning  An input file uses obsolete, discouraged or non-portable
>              syntax.  All the same, the meaning of the input is
>              unambiguous and a correct rendering can be produced.
>
> Which is, here, dropping the .SM and rendering "something"
> as plain bold.

Ingo,

Thanks for the clarification---the language is pretty clear, I just 
wanted to be doubly-sure that downgrading was the correct solution.

Anyway, this has been fixed.  Thanks!

Kristaps

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv