On Tue, 17 Dec 2024 18:04:01 +0000 (UTC) Joseph Myers <josmy...@redhat.com> wrote:
> I don't think we should introduce man pages as a new source format > for documentation in GCC. Either .texi or .rst (with generated man > pages) would be fine. I hope you can be persuaded to accept our man pages, at least for now, because they exist. I don't see the harm. IMO good documention in any format is better than bad or missing documentation in any format. I've written documentation in mdoc, DocBook, and Texinfo. mdoc is far and away the most convenient, and needs the least machinery. I'm also working on a system to generate "railroad diagrams" from mdoc pages. For wordy languages like SQL and COBOL, RR diagrams are easier to read than the syntax we use for command-line utilities. If pandoc-generated texi output from mdoc is acceptable, I'm happy to provide that, too, in addition to the originals. I do see the value in an integrated gcc manual using a single format. The one thing the Texinfo system does better than any other is indexes and keyword lookup. > For parts of GCC using Sphinx, I'd like us to move towards common > build infrastructure A gimlet-eyed view is that the utopian promise of producing PDF, HTML, and terminal output from a single input has never, for any system, produced good results for all outputs. Different media have different capacities and requirements, things that cannot be satisfied via automation. The best output inevitably is the one the author cares about most. --jkl
