discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Ft/Fn vs. parentheses weirdness
@ 2014-11-19 22:36 Thomas Klausner
  2014-11-20  0:36 ` Ingo Schwarze
  0 siblings, 1 reply; 2+ messages in thread
From: Thomas Klausner @ 2014-11-19 22:36 UTC (permalink / raw)
  To: discuss

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

Hi!

I wanted to mark up a function like this:

int (*foo)(bar, baz)

using Ft/Fn. I noticed that I can't really do that, and found some
weird behaviour both with groff 1.19.2 and mandoc 1.13.0 (the newest I
have installed).

Can you please take a look at the attached test page and tell me

* if there is a way to do what I want?

* how many bugs I found? :)

For the record, this is what it looks like for me with groff:
# groff -mandoc -T ascii test.3 |less
test.3:24: environment stack underflow
test.3:24: cannot chop empty macro
TEST(3)                 NetBSD Library Functions Manual                TEST(3)

NAME
     test -- test page

SYNOPSIS
     Some weird Fn/Ft test cases

DESCRIPTION
   Case 1
     int
     bar(void)
     Function gets formatted even though inside a Bd literal.

   Case 2
     int (*foo()) bar baz

     Parentheses are in weird places, arguments are not taken as function
     argument.

   Case 3
     int Po(*foo)
     ) bar baz

     Loses Fn completely due to Po/Pc.

   Case 4
     int (*foo)(bar, baz)

     This is what I wanted, but the parentheses are marked up in bold.

NetBSD 7.0                     November 19, 2014                    NetBSD 7.0

and mandoc:


# mandoc test.3 |less
TEST(3)                    Library Functions Manual                    TEST(3)

NAME
     test -- test page

SYNOPSIS
     Some weird Fn/Ft test cases

DESCRIPTION
   Case 1
     int
     bar(void)
     Function gets formatted even though inside a Bd literal.

   Case 2
     int (*foo()) bar(baz)

     Parentheses are in weird places, arguments are not taken as function
     argument.

   Case 3
     int (*foo) bar baz

     Loses Fn completely due to Po/Pc.

   Case 4
     int (*foo)(bar, baz)

     This is what I wanted, but the parentheses are marked up in bold.

NetBSD 7.99.1                  November 19, 2014                 NetBSD 7.99.1


Thanks,
 Thomas

[-- Attachment #2: test.3 --]
[-- Type: text/plain, Size: 543 bytes --]

.Dd November 19, 2014
.Dt TEST 3
.Os
.Sh NAME
.Nm test
.Nd test page
.Sh SYNOPSIS
Some weird Fn/Ft test cases
.Sh DESCRIPTION
.Ss Case 1
.Bd -literal
.Ft int
.Fn bar void
.Ed
Function gets formatted even though inside a Bd literal.
.Ss Case 2
.Ft int
.Fn ( *foo ) bar baz
.Pp
Parentheses are in weird places, arguments are not taken as
function argument.
.Ss Case 3
.Ft int
.Fn Po *foo Pc bar baz
.Pp
Loses Fn completely due to Po/Pc.
.Ss Case 4
.Ft int
.Fn (*foo) bar baz
.Pp
This is what I wanted, but the parentheses are marked up in bold.

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

* Re: Ft/Fn vs. parentheses weirdness
  2014-11-19 22:36 Ft/Fn vs. parentheses weirdness Thomas Klausner
@ 2014-11-20  0:36 ` Ingo Schwarze
  0 siblings, 0 replies; 2+ messages in thread
From: Ingo Schwarze @ 2014-11-20  0:36 UTC (permalink / raw)
  To: Thomas Klausner; +Cc: discuss

Hi Thomas,

Thomas Klausner wrote on Wed, Nov 19, 2014 at 11:36:36PM +0100:

> I wanted to mark up a function like this:
> int (*foo)(bar, baz)

The best way i'm aware of is

  .Ft int
  .Fo \fR(*\fPfoo\fR)\fP
  .Fa bar baz
  .Fc

or

  .Ft int Fn \fR(*\fPfoo\fR)\fP bar baz

if everything is very short.

Arguably, you might wish that

  .Ft int
  .Fo ( *foo )
  .Fa bar baz
  .Fc

would work, but it doesn't.  There are three problems with it:

 1. .Fo only takes one argument, so ")" is ignored.
 2. "*" ends up in boldface.
 3. To solve 1., we have a choice of two evils:
     a) Choosing the second argument ")" to stay in scope,
        it would an up in boldface.
     b) Choosing to let ")" fall off the end of the scope,
        it would end up after the function arguments,
        as if ".Fc )" had been given.

Of course, it would be possible to change the rules such that
option a) is chosen but only the first argument gets formatted
using boldface, but that's of some complexity.  An equivalent
way to express that would be to say that the ")" is inside the
BLOCK, after the HEAD, before the BODY, but currently, TEXT
children are not supported in BLOCK nodes.

> using Ft/Fn. I noticed that I can't really do that, and found some
> weird behaviour both with groff 1.19.2 and mandoc 1.13.0 (the newest I
> have installed).
> 
> Can you please take a look at the attached test page and tell me
> * if there is a way to do what I want?
> * how many bugs I found? :)

Two, apparently.

 1. The first argument of .Fn is not supposed to be parsed.
 2. The .Fn macro is not supposed to reopen its scope after punctuation.

[...]
> .Ss Case 1
> .Bd -literal
> .Ft int
> .Fn bar void
> .Ed
> Function gets formatted even though inside a Bd literal.

The .Bd -literal block has nothing to do with the problem at hand.
It does three things:

 1. Disable filling (preserve white space and line break)
 2. Select typewriter (fixed width) font
 3. Left indent (optional, not used in your example above)

It does *not* disable any macro processing.

> .Ss Case 2
> .Ft int
> .Fn ( *foo ) bar baz
> .Pp
> Parentheses are in weird places, arguments are not taken as
> function argument.

Yes.  The opening delimiter falls out of the beginning of the macro,
but the closing delimiter terminates the .Fn macro.  I fixed the
bug of mandoc(1) reopening the .Fn scope afterwards, see the second
chunk below.

> .Ss Case 3
> .Ft int
> .Fn Po *foo Pc bar baz
> .Pp
> Loses Fn completely due to Po/Pc.

Yes, the function name is "Po", and there is the second mandoc bug,
see the first chunk below.

Yours,
  Ingo


Index: mdoc_macro.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_macro.c,v
retrieving revision 1.100
diff -u -p -r1.100 mdoc_macro.c
--- mdoc_macro.c	17 Nov 2014 06:44:35 -0000	1.100
+++ mdoc_macro.c	20 Nov 2014 00:21:22 -0000
@@ -924,7 +924,8 @@ in_line(MACRO_PROT_ARGS)
 			break;
 		}
 
-		ntok = ARGS_QWORD == ac ? MDOC_MAX : lookup(tok, p);
+		ntok = (ac == ARGS_QWORD || (tok == MDOC_Fn && !cnt)) ?
+		    MDOC_MAX : lookup(tok, p);
 
 		/*
 		 * In this case, we've located a submacro and must
@@ -989,6 +990,8 @@ in_line(MACRO_PROT_ARGS)
 			if (scope && ! rew_elem(mdoc, tok))
 				return(0);
 			scope = 0;
+			if (tok == MDOC_Fn)
+				mayopen = 0;
 		} else if (mayopen && !scope) {
 			if ( ! mdoc_elem_alloc(mdoc, line, ppos, tok, arg))
 				return(0);
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

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

end of thread, other threads:[~2014-11-20  0:36 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-11-19 22:36 Ft/Fn vs. parentheses weirdness Thomas Klausner
2014-11-20  0:36 ` 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).