On 09/16/2018 12:42 PM, Nils Gillmann wrote: > Christian Grothoff transcribed 8.3K bytes: >> Hi Nils, >> >> (1) our handbooks should be "real" books. For example, the GNU >> libmicrohttpd manual can even be ordered in print. We should strive for >> our documentation to be of book quality. >> >> (2) Texinfo is the offical documentation standard for the GNU project. >> Alone for the sake of keeping all things GNU uniform (we're building the >> GNU operating system!), we _will_ stick to Texinfo unless the GNU >> project decides to switch to a different documentation standard. > > Okay, as a maintainer your opinion and views count.
Actually, as maintainer it is my job to make sure we follow overall GNU guidelines. > So going by (2): Before I wrote this email I started working on > making a best effort auto-generation of the documentation output > to mdoc with texi2mdoc. There is nothing inherently wrong with exporting / converting to additional formats, not sure if it's worth the effort, but that's another story. > Some changes to the documentation have to be considered, for example > I am generally looking to get rid of the footnotes and include them > better in the text. That generally sounds reasonable, footnotes (except for certain citation styles) are rarely ideal in documentation. > This is not because texi2mdoc just ignores > footnotes. What can't be fixed would be fixed by hand. > Would it be okay to include these auto-generated pages, and let them > point out they are autogenerated, for people/OS' who do not want > to build with texinfo? Define 'include'. On the Web site? Sure. In the TGZ? Maybe, if there is really non-trivial demand _and_ the size in crease is thus justifiable. As an optional build option: if it's maintained, always. >> As for build issues with the documentation not being addressed nicely / >> in a timely fashion, the answer should be to get our CI to notify >> committers via e-mail when they break something. > > I think it should be different: breaking commits should not get in. For documentation, that'd be fine. For code, it's not always easy to say if a commit is breaking (different platforms, non-deterministic test case failures, etc.). But I do agree with DVN's general plan of ideally first committing to a branch, running the CI on multiple platforms and then auto-merging if it was OK (even though we might need an override mechanism). > I have made bad texinfo commits before and especially in the beginning > or when you just rush it, it is easy to overlook a detail and make a > mistake. Sure. Mistakes happen. But we also don't want to have an enforcement regime that basically prevents people from making progress.
signature.asc
Description: OpenPGP digital signature
_______________________________________________ GNUnet-developers mailing list [email protected] https://lists.gnu.org/mailman/listinfo/gnunet-developers
