SYNOPSIS and auto-Bk

SYNOPSIS and auto-Bk

[Kristaps Dzonsons]

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

Hi,

The following patch enables SYNOPSIS sections (or blocks within the nS 
register) to behave as if `Bk -words' were wrapping the entire section.

This makes for nice-looking SYNOPSIS sections where authors have omitted 
the `Bk'; however, output would differ from groff, so I'm hesitant to 
enable it.  This has been tossed around for a while.

Thoughts?  (Yes, the patch must be tweaked a bit before it's actually 
checked in.)

Kristaps

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 815 bytes --]

Index: mdoc_term.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_term.c,v
retrieving revision 1.174
diff -r1.174 mdoc_term.c
334a335,337
> 	 *
> 	 * Also let SYNPRETTY sections behave as if they were wrapped in
> 	 * a `Bk' block.
337c340
< 	if (TERMP_KEEP & p->flags) {
---
> 	if (TERMP_KEEP & p->flags || MDOC_SYNPRETTY & n->flags) {
346a350,361
> 	}
> 
> 	/*
> 	 * Since SYNPRETTY sections aren't "turned off" with `Ek', we
> 	 * have to intuit whether we should disable formatting.
> 	 */
> 
> 	if ( ! (MDOC_SYNPRETTY & n->flags)) {
> 		if (n->prev && MDOC_SYNPRETTY & n->prev->flags)
> 			p->flags &= ~(TERMP_KEEP | TERMP_PREKEEP);
> 		if (n->parent && MDOC_SYNPRETTY & n->parent->flags)
> 			p->flags &= ~(TERMP_KEEP | TERMP_PREKEEP);

Re: SYNOPSIS and auto-Bk

[Kristaps Dzonsons]

>> The following patch enables SYNOPSIS sections (or blocks within the nS 
>> register) to behave as if `Bk -words' were wrapping the entire section.
>>
>> This makes for nice-looking SYNOPSIS sections where authors have omitted 
>> the `Bk'; however, output would differ from groff, so I'm hesitant to 
>> enable it.  This has been tossed around for a while.
>>
>> Thoughts?  (Yes, the patch must be tweaked a bit before it's actually 
>> checked in.)
>>
>> Kristaps
> 
> hi. i like the idea a lot.
> 
> the compatibility thing is a pain though. if it forces me to keep using
> Bk in pages. hopefully that will become less of an issue.
> 
> but i'm reluctant to run with the diff this close to release. i need to
> see what the mandoc we have is doing to pages.

That's fine: this patch won't get outdated, so we can sit on it.

When is the freeze?  I ask because I can put Ingo's recent check-ins 
into a mini-release and we can tag that out as the OpenBSD release 
version before I get to work on simplifying the special-character encoding.
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: SYNOPSIS and auto-Bk

[Kristaps Dzonsons]

>>> but i'm reluctant to run with the diff this close to release. i need to
>>> see what the mandoc we have is doing to pages.
>> That's fine: this patch won't get outdated, so we can sit on it.
>>
>> When is the freeze?  I ask because I can put Ingo's recent check-ins 
>> into a mini-release and we can tag that out as the OpenBSD release 
>> version before I get to work on simplifying the special-character encoding.
> 
> ooh, good question. i'm just aware that it can't be far. i'll ask and
> get back to you on that one.

Jason, note that "before I get to work" begat "the work".  I'll hold off 
on feature/formatting commits until the freeze: these last commits, 
which were purely internal, shaved ~14 KB off the binary as measured on 
my alpha.

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

Re: SYNOPSIS and auto-Bk

[Ingo Schwarze]

Hi Kristaps, hi Jason,

Kristaps Dzonsons wrote on Fri, Jul 16, 2010 at 10:05:23PM +0200:
> Jason McIntyre wrote:
>> Kristaps wrote:

>>> The following patch enables SYNOPSIS sections (or blocks within
>>> the nS register) to behave as if `Bk -words' were wrapping the
>>> entire section.
>>>
>>> This makes for nice-looking SYNOPSIS sections where authors have
>>> omitted the `Bk'; however, output would differ from groff, so
>>> I'm hesitant to enable it.  This has been tossed around for a
>>> while.
>>>
>>> Thoughts?  (Yes, the patch must be tweaked a bit before it's
>>> actually checked in.)

>> hi. i like the idea a lot.
>>
>> the compatibility thing is a pain though. if it forces me to keep using
>> Bk in pages. hopefully that will become less of an issue.
>>
>> but i'm reluctant to run with the diff this close to release. i need to
>> see what the mandoc we have is doing to pages.

> That's fine: this patch won't get outdated, so we can sit on it.

Concerning this patch, i tend to agree that we should hold it off
until after release.  It is not strictly needed to fix remaining
SYNOPSES, in case any remain in a broken state; or at least they
can as well be fixed with plain .Bk for now, if we find them.
On the other hand, the patch is slightly dangerous and might
break other stuff that may not necessarily be easy to find.

So, this on shouldn't go in in a hurry, even though we all like
the idea.

> When is the freeze?

No idea, that's notoriously hard to predict,
but i don't think it will happen just tomorrow.

> I ask because I can put Ingo's recent check-ins
> into a mini-release and we can tag that out as the OpenBSD release
> version

I tend to think it is too early to tag any kind of OpenBSD release
version just yet.  Let's rather think about that when we know for
sure when the lock will happen.

> before I get to work on simplifying the special-character encoding.

My suggestion would be that, until the *unlock* happens - which is
typically about a week after the final hard lock - all of us abstain
from starting any kind of refactoring (except when required to fix
bugs) and fully concentrate on bug fixing.

Until the first soft lock is announced, we can just go ahead and fix
whatever bugs we find - though the later it gets, the more care should
be put into testing, for obvious reasons.  When soft lock is announced,
we should really concentrate on finding and fixing *critical* bugs;
with special OKs, critical fixes can still go in at that stage.
Also, manual page fixes can typically still go in for a few days
after lock.

At some point, there will be a call for release testing.
Of course, any help with that is also very welcome.

Right after unlock will be a very good time to start any kind
of refactoring.

Yours,
  Ingo


P.S.
Just for your information, here is a table of tagging dates.
The more recent ones are probably closer to what might happen this year,
but one never really knows...
The "CURRENT" column corresponds to unlock, the "RELEASE" column
is usually close to the final hard lock, the initial soft lock
typically happens around the "BETA" phase.

    BETA  RELEA CURRE       BETA  RELEA CURRE

4.8 ???   ???   ???     4.7 Jan26 Mar05 Mar18   2010
4.6 Jun20 Jul01 Jul05   4.5 Feb08 Feb26 Mar01   2009
4.4 Jul02 Aug06 Aug07   4.3 Feb20 Mar04 Mar08   2008
4.2 Jul25 Aug05 Aug21   4.1 Feb12 Mar01 Mar12   2007
4.0 Jul26 Aug28 Sep17   3.9 Jan19 Feb27 Mar04   2006
3.8 Aug09 Aug27 Sep05   3.7 Mar07 Mar15 Mar21   2005
3.6 Aug09 Aug20 Sep14   3.5 Feb27 Mar09 Apr05   2004
3.4 Aug11 Sep02 Sep15   3.3 Feb12 Mar04 Mar27   2003
3.2 Sep10 Oct01 Oct04   3.1 Mar22 Apr11 Apr15   2002
3.0 Sep11 Oct15 Oct24   2.9 Apr15 Apr19 May06   2001
2.8 Aug21 Oct20 Nov07   2.7 Apr08 May04 May15   2000
2.6 Sep23 Oct14 Nov27   2.5 Feb28 Mar30 Apr18   1999
2.4             Sep15   2.3             Mar07   1998
2.2             Oct01   2.1             Apr28   1997
2.0             Oct03                           1996
1.2             Oct23                           1995
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv