Re: move roff sections to a separate file

[Ingo Schwarze <schwarze@usta.de>]

Hi Yuri,

Yuri Pankov wrote on Tue, May 30, 2017 at 03:09:06AM +0300:
> On Tue, 30 May 2017 01:47:17 +0200, Ingo Schwarze wrote:

>>   3. Technically, i don't like the concept of *.in files at all.
>>      They make reading the code harder, as they are neither fish nor
>>      fowl, neither proper, readable C code, nor proper, readable *.h
>>      headers.  I want to slowly get rid of them.  I have deleted a
>>      few already and hope to continue in that direction, even if not
>>      with terribly high priority.  But i certainly don't want to add
>>      any more of them.

> That's unfortunate as .in files allow us to keep the man sections
> (msec.in) and library (lib.in) descriptions separate of the code

Oh.  Yeah.  Don't panic about those two.  Regarding msec.in, that's
the one of these files where i don't see any realistical chance to
get rid of it in any forseeable future.  That indeed varies so
wildly among systems for historical reasons that there is little
hope of convergence.

Regarding lib.in, i had half forgetten about it already because it
was deleted from OpenBSD long ago.  We don't use the .Lb macro at
all.  But lib.in was expressly kept in the portable distribution
because illumos isn't the only system out there that likes grooming
a bewildering zoo of libraries.  Free, Net, and DragonFly rely on
that too, so it's not going away either.

But as soon as i have to touch st.c for some reason, st.in
is likely to die, and one day, predefs.in might get swallowed up
by roff.c, or by a similar file in the neighbourhood.


[...]
> We have CONTEXT section after RETURN VALUES.

Hmmm.  You have a point here.  We added that section recently
in OpenBSD, and maybe it was premature to make it public in this
way.

I'm currently working on a -Wstyle message level.  That is likely
to need some system dependencies anyway.  I haven't worked out
the required concepts of system dependency yet, but hope to
keep them as simple as possible.  Maybe that will yield a natural
solution.

For the next update of your tree (probably to 1.14.1), i suggest
that you simply maintain a local 4-line patch for CONTEXT; it
shouldn't be too burdensome, the enum doesn't change that
frequently upstream.

I'll try that you can get rid of it again.  In case i forget, it
might be useful to remind me in the context of the *next* update
after that.

> The sections I listed below are standard for us, so there's a need
> to order them properly.
[...]
> We have the following sections in our man pages that aren't present
> currently in validation, and I don't think it'd make sense to add
> them as generic ones:
> 
> INTERFACE LEVEL (after SYNOPSIS and before DESCRIPTION)
> CODE SET INDEPENDENCE
> INTERFACE STABILITY
> MT-LEVEL

I see.  NetBSD has a similar need, they use COMPATIBILITY, CODE
REFERENCES, and SECURITY CONSIDERATIONS in some pages and want those
in a specific order.  While migrating functionality from mdoclint(1)
to mandoc(1) -Wall, i have to find a solution for that anyway, so
that will very likely solve the task for you, too.  The peculiar
ordering of CONTEXT in OpenBSD is of the same kind, i think.

While issues like SEE ALSO before DESCRIPTION are WARNINGS (such
an order would be wrong on any system), the system-specific checks
will probably end up in the lower STYLE message level, but that
shouldn't be a problem for you.

So i think i know now what i need to know when doing the (low-intensity)
work on the message system during the next few months.

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