Re: Document that find -maxdepth is a GNU extension

[James Youngman]

On Fri, Apr 26, 2019 at 7:28 AM Bernhard Voelker
<address@hidden> wrote:
>
> On 4/16/19 6:41 AM, Andreas Metzler wrote:
> > As a find user I would rather see the info manual dropped than the
> > manpage.

My recollection of user feedback is that most users who contact this
list feel the same way.

However the GNU project's policy is to maintain Texinfo documentation
and not require maintainers to maintain manpages.   I reconciled these
things by volunteering also to maintain the manpage.  That's quite in
accordance with GNU policy, though I guess they don't encourage it.

Now that I am not the only maintainer though, it's worth pointing out
that this is not a required thing.   It's up for discussion.

> > For *me* the latter is not only better accessible. man with
> > less a pager simply is quicker than any of the info readers or a
> > web-browser, but apart from that especially for find the man page is
> > better readable. There is less chaff. It is leaner since it only
> > documents find and not e.g. updatedb, too.

The key difference between the two types of documentation, apart from
length, is that the Texinfo manual tries to present all the tools
simultaneously while obviously the man pages don't do that.

> I'm personally using 'pinfo' instead of plain 'info' as reader,
> because I find the navigation there more natural.
>
> > Also I simply do not like fine-grained the node structure with deep
> > hierarchy. It is fine in theory, but if I am looking for e.g. printf
> > specifiers I am going to search for /printf/ instead of jumping through
> > TOC -> 3 Actions -> 3.2 Print File Information -> 3.2.2 Format
> > Directives -> 3.2.2.1 Name Directives.
>
> I agree, the structure of the whole document is looking quite odd
> to me as well.  But this is not a deficiency of the Tex language.
> It could be easily moved around a bit.
>
> > I do know that GNU standards say differently, but I respectfully
> > disagree.
>
> I'm not an expert for either format, but I think the Texinfo format
> is more powerful, and especially the converted formats - HTML as one
> page, HTML with a page per node, and finally PDF - are really nice.
>
> Ideally, we could generate the man page from the Texinfo manual,

Coreutils generates the man page from the --help output.   But, find
is a great deal more complex than most binaries in coreutils and
changing find to emit the bulk of the current manpage in the --help
output would be rather user-unfriendly.

> or the other way round, to avoid the double maintenance.  We've
> had quite some reports in the past couple of years that something
> is missing in either documentation.

I'm very sympathetic to the feedback that the parallel maintenance is
burdensome; after all, for a long time I carried the burden by myself.
  If we're looking for an alternative to manual maintenance of the two
documents in parallel, we might consider splitting the current Texinfo
manual into a reference and perhaps a tutorial.  The tutorial and
reference could form two parts of a single Texinfo manual, with the
reference also being used to generate the manpage.

That would, I think, require quite a lot of work and to be clear I'm
not proposing to do this myself, at least not in the near future.

> The problem is: whatever we decide (iff we ever come to a conclusion),
> we have to avoid to create much effort for our friends at:
>   https://translationproject.org/domain/findutils.html

I don't think the translation project translates the documentation.

Thanks,
James.