On Fri, Apr 26, 2019 at 7:28 AM Bernhard Voelker <m...@bernhard-voelker.de> 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.
