Re: [GNUnet-developers] proposal: changes to documentation

[Christian Grothoff]

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