Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a wrong section

[G. Branden Robinson]

At 2019-02-27T13:34:29+0100, Ingo Schwarze wrote:
> > as those are part of the interface of a macro package,
> 
> I think this phrase invites a misunderstanding.  With a library or
> macro package, the term "interface" is usually understood as "user
> interface" or "API", i.e. what application programs (or end-user
> documents like manual pages in the case of a macro package) are
> supposed to use.
> 
> But the .doc-* macros are specifically *NOT* intended for use by
> manual pages.  They are supposed to be *INTERNAL* implementation
> details of the mdoc(7) macro package, and as such, they can change
> at any time without any notice whatsoever.  The .doc-* prefix is
> specifically intended to stress the internal character of these
> macros and avoid clashes with user-defined macros - even though
> defining macros inside manual pages certainly wouldn't be good
> style, it still makes sense that a macro set keeps the global
> namespace as clean as possible.  Just like a library might start
> the names of private, internal symbols that application programs
> are not supposed to access with, e.g., an "_" prefix.

Ah, okay, I stand corrected.  groff doesn't have namespaces or true
lexical scopes--though I would not dare assert that they could not be
hacked into existence--and I am too unfamiliar with mdoc to know which
symbols are intended for use by man page writers and which aren't.

> > Come to think of it, because this _was_ an interface change for mdoc,
> > this change should have been documented in the NEWS file for groff
> > 1.22.4.  That it was not was my oversight, and I apologize.
> 
> Branden, i respectfully disagree, and quite strongly.  You did nothing
> wrong.  This was not an interface change, certainly not in the sense
> that needs to be announced to users.  It was a purely internal
> implementation change, entirely irrelevant for users.

Ah, okay.  Well, if I _didn't_ screw up, I'll accept that.  :)

>     I'm not sure whether it is better for you to include or not
>     include it.  There is probably value in having mdoc(7) documentation
>     out of the box with the Linux man-pages project.  Then again,
>     having groff_mdoc(7) in both the Linux man-pages package and
>     in the groff package - or having mdoc(7) in both the Linux
>     man-pages project and the mandoc(1) package - might cause
>     packaging conflicts for some distributions.

This should not be a problem for any self-respecting distribution.
Package maintainers frequently choose not to "ship" certain files in
certain packages due to conflicts/overlap, and sophisticated package
management systems (like dpkg) allow for migration of files between
packages across upgrades, with rollback in case of problems.

>     I don't rightly know how such conflicts are typically handled by
>     Linux distributions.  Not being able to install the Linux
>     man-pages pages project, groff(1) and mandoc(1) all together on
>     the same Linux machine would certainly be a bad situation...

I don't think has been a technical challenge for at least 25 years.

Regards,
Branden

signature.asc
Description: PGP signature