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
Attachment:
signature.asc
Description: PGP signature
