Re: A file suffix for troff's output. (Was: pdfroff in groff 1.23.0.rc3 changes compared to 1.22.4)

[Alejandro Colomar]

Hi Steve,

On 4/10/23 15:45, Steve Izma wrote:
> On Mon, Apr 10, 2023 at 10:03:34AM +0100, Ralph Corderoy wrote:
>> Subject: A file suffix for troff's output. (Was: pdfroff in groff
>>  1.23.0.rc3 changes compared to 1.22.4)
>>
>>     troff chapter.tr >chapter.set
>>     grops chapter.set >chapter.ps
>>
>> Short, simple, not already widely used by another program,
>> pronounceable, a clear derivation.
> 
> Maybe I'm mis-reading the problem here, but Postscript output
> from groff in my experience has always been a temporary file.

I have a need for temporary files in the Linux man-pages repo.
In the build system, I produce every possible temporary file, so
that I can see what each filter is doing, and can debug more
easily when one of them doesn't behave well.

Keeping all of the temporary files in the build tree is simpler
than having to build those files when I need them.  It also
allows me to write simpler rules, which I can manage with more
granularity.

Here's what I have in the build tree for the membarrier.2 page:


$ find .tmp/ | grep membarrier
.tmp/man/man2/membarrier.2.cat.grotty
.tmp/man/man2/membarrier.2.eqn
.tmp/man/man2/membarrier.2.cat.troff
.tmp/man/man2/membarrier.2.lint-man.tbl.touch
.tmp/man/man2/membarrier.2.cat
.tmp/man/man2/membarrier.2.lint-man.mandoc.touch
.tmp/man/man2/membarrier.2.d
.tmp/man/man2/membarrier.2.d/membarrier.lint-c.clang-tidy.touch
.tmp/man/man2/membarrier.2.d/membarrier.lint-c.cppcheck.touch
.tmp/man/man2/membarrier.2.d/membarrier.lint-c.checkpatch.touch
.tmp/man/man2/membarrier.2.d/membarrier.lint-c.iwyu.touch
.tmp/man/man2/membarrier.2.d/membarrier.lint-c.cpplint.touch
.tmp/man/man2/membarrier.2.d/membarrier.c
.tmp/man/man2/membarrier.2.check-catman.touch
.tmp/man/man2/membarrier.2.tbl
.tmp/man/man2/membarrier.2.cat.grep


So far, I called them .grotty, because I only used grotty(1) so
far, but .set would be more appropriate.  I'd use .cat.set
for UTF8/ASCII pages, and .html.set for HTML pages.


And I still want to add more:

-  HTML pages, which would add the following files:

   -  .tmp/man/man2/membarrier.2.html.troff
   -  .tmp/man/man2/membarrier.2.html.set
   -  .tmp/man/man2/membarrier.2.html

-  Intermediate files for C (.i, .s, .o).

And maybe more.

Here's the Makefile that handles (some of) those files:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/build-catman.mk#n78

> I
> am usually working on several projects at once, with output file
> names that never seem to clash, so all of my output files from
> groff processing automatically go to /home/ps. This
> 
> - works as a kind of tmp directory (but clear of all system tmp
>   files);
> - is under the /home hierarchy so can be easily added to backups
>   if I feel it necessary (almost always not);
> - can be easily cleared out, either entirely or according to age
>   (presuming age = possible obsolescence);
> - follows what I think is a clearer way of defining the nature of
>   a file: it's location within the filesystem hierarchy, identity
>   defined by its parent's name (i.e., "ps");

In a build tree, you can have a subtree for each type of temporary
file, but to me it's simpler to have a single hierarchy, and
suffixes that say which temporary file it is.

> - utilities like ps2pdf do not require suffixed files for input
>   validation;

Few programs do.  It's more for humans to keep stuff organized.

> - it's worked for me with virtual no problem for over 30 years
>   (but I'm only one test case, I guess).
> 
> So why all the fuss? One could also argue that a Postscript file
> is a text file and I avoid .txt extensions as much as possible.

Except for a few binary files, most files in Unix are text files.
However, that doesn't mean it's text targeted at humans, but at a
specific program that happens to read certain text.

We do use .c extensions, but they are text (maybe not readable
for non-programmers, but text after all), and the compiler
accepts -x c for specifying the language.  It's more for us
humans to know what's in a file.

As Ralph said, it can also help create rules in Makefiles based
on file suffixes.

> After all, as far as I can tell, .txt was a Microsoft invention,
> another step in Bill Gates's war to obstruct Unix conventions.
> And under Unix one could reasonably argue that an un-suffixed
> file outside of bin directories was by default a text file.
> 
> The same argument holds for putting troff source files into a tr
> subdirectory of your project directory. That keeps the main
> project directory uncluttered.
> 
>       -- Steve
> 

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature