tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Strange error on a manpage
@ 2014-12-26 20:36 Baptiste Daroussin
  2014-12-26 20:56 ` Franco Fichtner
  0 siblings, 1 reply; 4+ messages in thread
From: Baptiste Daroussin @ 2014-12-26 20:36 UTC (permalink / raw)
  To: tech

[-- Attachment #1: Type: text/plain, Size: 468 bytes --]

Hi,

The FreeBSD's netmap(4) manpage has 2 failures that seems weird to me

mandoc: ./netmap.4:932:2: ERROR: skipping unknown macro: ...
mandoc: ./netmap.4:967:2: ERROR: skipping unknown macro: ...

https://svnweb.freebsd.org/base/head/share/man/man4/netmap.4?revision=276236&view=markup

What seems weird: it finds ... in .Bd section and consider it as an error, I
would expect mandoc not to try to resolv macros inside a .Bd section, am I
wrong?

Best regards,
Bapt

[-- Attachment #2: Type: application/pgp-signature, Size: 181 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Strange error on a manpage
  2014-12-26 20:36 Strange error on a manpage Baptiste Daroussin
@ 2014-12-26 20:56 ` Franco Fichtner
  2014-12-26 21:02   ` Baptiste Daroussin
  2014-12-28 10:35   ` Ingo Schwarze
  0 siblings, 2 replies; 4+ messages in thread
From: Franco Fichtner @ 2014-12-26 20:56 UTC (permalink / raw)
  To: tech; +Cc: Baptiste Daroussin

On 26 Dec 2014, at 21:36, Baptiste Daroussin <bapt@FreeBSD.org> wrote:

> The FreeBSD's netmap(4) manpage has 2 failures that seems weird to me
> 
> mandoc: ./netmap.4:932:2: ERROR: skipping unknown macro: ...
> mandoc: ./netmap.4:967:2: ERROR: skipping unknown macro: ...
> 
> https://svnweb.freebsd.org/base/head/share/man/man4/netmap.4?revision=276236&view=markup
> 
> What seems weird: it finds ... in .Bd section and consider it as an error, I
> would expect mandoc not to try to resolv macros inside a .Bd section, am I
> wrong?

vim syntax highlighting picks these lines up as well.  It must
parse them in order to find `.Ed', so I think the error correct.

The line can be escaped using `\&...' or replaced by an empty
line.  Maybe wrapping them into a C comment would also be ok.

I don't see the point of obfuscating the source code snippet with
just the dots.


Cheers,
Franco--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Strange error on a manpage
  2014-12-26 20:56 ` Franco Fichtner
@ 2014-12-26 21:02   ` Baptiste Daroussin
  2014-12-28 10:35   ` Ingo Schwarze
  1 sibling, 0 replies; 4+ messages in thread
From: Baptiste Daroussin @ 2014-12-26 21:02 UTC (permalink / raw)
  To: tech

[-- Attachment #1: Type: text/plain, Size: 1079 bytes --]

On Fri, Dec 26, 2014 at 09:56:08PM +0100, Franco Fichtner wrote:
> On 26 Dec 2014, at 21:36, Baptiste Daroussin <bapt@FreeBSD.org> wrote:
> 
> > The FreeBSD's netmap(4) manpage has 2 failures that seems weird to me
> > 
> > mandoc: ./netmap.4:932:2: ERROR: skipping unknown macro: ...
> > mandoc: ./netmap.4:967:2: ERROR: skipping unknown macro: ...
> > 
> > https://svnweb.freebsd.org/base/head/share/man/man4/netmap.4?revision=276236&view=markup
> > 
> > What seems weird: it finds ... in .Bd section and consider it as an error, I
> > would expect mandoc not to try to resolv macros inside a .Bd section, am I
> > wrong?
> 
> vim syntax highlighting picks these lines up as well.  It must
> parse them in order to find `.Ed', so I think the error correct.
> 
> The line can be escaped using `\&...' or replaced by an empty
> line.  Maybe wrapping them into a C comment would also be ok.
> 
> I don't see the point of obfuscating the source code snippet with
> just the dots.
> 
I will escape the dot thank you for the suggestion

Best regards,
Bapt

[-- Attachment #2: Type: application/pgp-signature, Size: 181 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Strange error on a manpage
  2014-12-26 20:56 ` Franco Fichtner
  2014-12-26 21:02   ` Baptiste Daroussin
@ 2014-12-28 10:35   ` Ingo Schwarze
  1 sibling, 0 replies; 4+ messages in thread
From: Ingo Schwarze @ 2014-12-28 10:35 UTC (permalink / raw)
  To: Baptiste Daroussin; +Cc: tech

Hi Baptiste and Franco,

Franco Fichtner wrote on Fri, Dec 26, 2014 at 09:56:08PM +0100:
> On 26 Dec 2014, at 21:36, Baptiste Daroussin <bapt@FreeBSD.org> wrote:

>> The FreeBSD's netmap(4) manpage has 2 failures that seems weird to me
>> 
>> mandoc: ./netmap.4:932:2: ERROR: skipping unknown macro: ...
>> mandoc: ./netmap.4:967:2: ERROR: skipping unknown macro: ...
>> 
>> What seems weird: it finds ... in .Bd section and consider it as an
>> error, I would expect mandoc not to try to resolv macros inside a .Bd
>> section, am I wrong?

Here is what the mdoc(7) manual says below "Bd":

     Display blocks are used to select a different indentation and
     justification than the one used by the surrounding text.
     They may contain both macro lines and text lines.

It is a somewhat common misconception that .Bd would disable
macro processing, but that's not at all what it does.

The manual continues:

      -literal   Produce one output line from each input line, and do
                 not justify the block at all.  Preserve white space
                 as it appears in the input.  Always use a constant-
                 width font.  Use this for displaying source code.

So even that does *not* disable any macro processing.

> vim syntax highlighting

Syntax highlighting tends to be crap.  I cannot think of any worse
syntax checker than a syntax highlighter.  If you want to do syntax
checking, use a validating compiler (or interpreter, depending on
the language in question).  Take syntax highlighting for what it
is: half-assed, useless guesswork that is usually wrong when it
matters.

I would consider vim to be particularly non-authoritative.

> picks these lines up as well.  It must parse them in order to
> find `.Ed',

That is true, but a rather weak reason: For example, the roff(7)
.if request does parse subsequent lines specifically for the ..
end-of-conditional request as well as for sub-conditionals, but all
the same disables most other request processing and all macro
processing.  So it is possible - and in some situations implemented -
to *selectively* disable request and macro processing.

> so I think the error correct.

It is, but the true reason is that the mdoc(7) language intentionally
does not contain any macro to (temporarily) disable macro processing.
Escaping is always needed, in any context.

> The line can be escaped using `\&...' or replaced by an empty
> line.

That's the conventional way to escape leading "." and "'", indeed.

>  Maybe wrapping them into a C comment would also be ok.

That sounds like even better style for the particular case at hand.

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-12-28 10:35 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-12-26 20:36 Strange error on a manpage Baptiste Daroussin
2014-12-26 20:56 ` Franco Fichtner
2014-12-26 21:02   ` Baptiste Daroussin
2014-12-28 10:35   ` Ingo Schwarze

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).