bugGNU troff - Bugs: bug #51003, "test-groff" can't find...

 
 

bug #51003: "test-groff" can't find doc-macros in the "tmac/mdoc" directory

Submitted by:  Bjarni Ingi Gislason <bjarniig>
Submitted on:  Thu 11 May 2017 03:21:40 PM UTC  
 
Category: NoneSeverity: 3 - Normal
Item Group: NoneStatus: None
Privacy: PublicAssigned to: None
Open/Closed: OpenPlanned Release: None

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Sat 13 May 2017 03:10:50 PM UTC, comment #4:

> It could (to whom?, and why?. Is it solvable?).


To developers trying to maintain groff, and to users trying to install it from source, trying to port it to new platforms, and trying to debug problems they encounter. Because build systems are already complicated without adding needless complication.

It is not completely solvable. A build system of software as complex as groff will always remain complicated. The best we can do is keep it as simple as possible.

It is NOT the job of a build system to try and create a half-working pseudo-installation inside the source directory. The job of the source tree is to contain one copy of each required source file in a place that is logical for development (and not as an installation location). The job of the build system is to read the source files and create one copy of each required autogenerated file, in whichever location in the build directory is simplest. The job of the install target is to copy these autogenerated files (and maybe some source files) to as many installation locations as required for the software to work. Mixing up these jobs is a recipe for confusion and bugs.

> Creating the missing directory and the links in the
> git-repository was for me the simplest solution.


It doesn't even work reliably. If you follow the advice in INSTALL.REPO to create a separate build directory, it will fail.

> Another is to let the Makefile create the directory and links.


Yeah, somehere is tmac/tmac.am or somewhere similar, that might work. But it's likely to remain fragile, and it will definitely add additional complexity to the build system. We should strive to simplify the build system, not make it even more complicated than it already is.

Really, hacking around in order to make test-groff better is not worth making maintenance harder and increasing the risk of bugs in the released software.

Ingo Schwarze <schwarze>
Sat 13 May 2017 01:10:18 AM UTC, comment #3:

> Follow-up Comment #1, bug #51003 (project groff):
>
> I suspect this ticket to be invalid.
>


A suspicion is a guess. I have not seen any (valid) evidence for it to
be true.

> > Man-pages include "doc"-macros with a request ".mso mdoc/...".
>
> No. They don't. In the complete OpenBSD ports tree (nearly 10k ports), i'm
> not aware of a single port doing that.
>


You are right in a way. Clumsy wording on my part. Better is
'"doc"-macros are included with a request ".mso mdoc/..." if needed."
I was pointing out how the directory "mdoc" is involved in the inability of
"test-groff" to function correctly.

[...]

> > A fix could be
>
> A fix for what exactly? Which problem are you trying to solve?
>


My subject line shows that.
And a solution would also get rid of the following in the "PROBLEMS" file:

"* Processing mdoc man pages like `groff_mdoc.n' fails if I use
`test-groff'. Why?

The mdoc package works only after installation, not with test-groff.
Reason is that the macro files of mdoc get stripped off the `doc-'
prefix before they are copied to the final destination."

> > to create the directory and links in that directory
>
> Certainly not. There is no need whatsoever to have duplicate versions of
> files in the source tree. That would only cause confusion.
>


It could (to whom?, and why?. Is it solvable?). Creating the missing
directory and the links in the git-repository was for me the simplest
solution.
Another is to let the Makefile create the directory and links. And adding
"tmac/mdoc" to the ".gitignore" file. See for example "build-aux".

[...]

Bjarni Ingi Gislason <bjarniig>
Thu 11 May 2017 08:45:15 PM UTC, comment #2:

Oops, sorry for missing the first word of the bug title. But i still think there is no problem. I have often worked on bugfixing in the mdoc macros, but a need to test them with ./test-groff never came up. "Fixing" that isn't worth any complication.

Ingo Schwarze <schwarze>
Thu 11 May 2017 08:13:40 PM UTC, comment #1:

I suspect this ticket to be invalid.

> Man-pages include "doc"-macros with a request ".mso mdoc/...".


No. They don't. In the complete OpenBSD ports tree (nearly 10k ports), i'm not aware of a single port doing that.

If any manual page would do that, it would be extremely bad style, not serving any purpose whatsoever but introducing pointless fragility. No manual page should ever contain any .mso request.

The way to format a manual page is calling "nroff -mandoc" (or troff -mandoc). If you are sure it is mdoc(7) and not man(7), you can also say "nroff -mdoc", but there is no real reason why the user should bother. The page itself certainly must not attempt to second-guess the system roff installation.

> The directory "mdoc" does not exist in the git-repository.


True. But for one thing, source directory layout need not match the layout of the installed software. Here, a directory like ".../groff/1.22.3/tmac/mdoc/" does get created at install time, see tmac/tmac.am, variable $(mdocdir) for details.

Then, it doesn't matter. All that is called externally - and not by the end user or the manpage itself, but by man(1)! - is the main macro file, ../groff/1.22.3/tmac/doc.tmac, which is not inside the mdoc/ subdir. That file includes whatever it needs.

> A fix could be


A fix for what exactly? Which problem are you trying to solve?

> to create the directory and links in that directory


Certainly not. There is no need whatsoever to have duplicate versions of files in the source tree. That would only cause confusion.

> A comment in "doc.tmac":


Admittedly, that comment is ridiculous nowadays. If worrying about systems unable to handle filenames longer than 8+3 bytes ever made sense (which i doubt), those times are over for at least two decades. But i don't see much benefit in renaming stuff, the current names work and people got used to them. Maybe the comment could be changed to say "nonstandard naming for historical reasons", but that doesn't seem very pressing either.

Ingo Schwarze <schwarze>
Thu 11 May 2017 03:21:40 PM UTC, original submission:

Man-pages include "doc"-macros with a request ".mso mdoc/...".

The directory "mdoc" does not exist in the git-repository.

A fix could be to create the directory and links in that directory
to the "doc-" files (doc-common, doc-ditroff, doc-nroff, and doc-syms).

A comment in "doc.tmac":

.\" Modified by -unavailable- as follows: the doc-* files are assumed to be
.\" installed as mdoc/doc-* rather than tmac.doc-* (the filename
.\" `tmac.doc-common' would be too long); when using groff, the doc-* files
.\" are loaded using the `mso' request.

Bjarni Ingi Gislason <bjarniig>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by schwarze (Posted a comment)
  • -unavailable- added by bjarniig (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item

    Back to the top


    Powered by Savane 3.1-cleanup1