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