Re: Document that find -maxdepth is a GNU extension

[Bernhard Voelker]

Hi James,

On 5/4/19 2:06 AM, James Youngman wrote:
> 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.

I agree.

>> 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.

Yes, good idea.

> 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.

Indeed, let's rather cut 4.7.0 first.

Re-organizing documentation is an unpopular task, but given there are
excellent pieces in either format and missing in the other format,
it would really make sense soon to consolidate to a "single source".
The way you outlined above sounds like a great approach.

>> 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.

Ah, that's great.

> Thanks,
> James.

Thanks & have a nice day,
Berny