View Issue Details

IDProjectCategoryView StatusLast Update
0005517GNUnetdocumentationpublic2019-06-15 15:41
Reporterng0Assigned Tong0 
PrioritynormalSeverityfeatureReproducibilityhave not tried
Status resolvedResolutionfixed 
Product Version 
Target Version0.11.6Fixed in Version0.11.6 
Summary0005517: man changes
DescriptionWe use a really limited subset of groff for our mostly really short manpages.

Recent man-pager implementations all(? at least all major ones I know of) support parsing the newer mdoc format.
The mdoc format for myself as a writer requires much less interruption of readability when I write it.
Since we lose nothing and only gain the ability to read the sourcecode of the man pages better, I want to convert the groff to mdoc.
While I would work on this, I would also standardize our sections, dates, and so forth.

Converting to this format makes it easier to write the pages, regardless of what FSF has to say on that matter.

We don't need this for mdoc man-pager to read the pages, as the support goes both ways. This is just to ease writing the pages and reading them, plus a bit of standardization.
Tagsdocumentation

Activities

Christian Grothoff

2019-02-14 12:12

manager   ~0013752

I am pretty sure GNU doesn't mandate groff for man pages. IIRC what is *suggested* is actually to generate them from the texinfo, something demonstrated in GNU Hello. GNU officially uses 'info' pages, 'man' pages are just an optional thing we are "allowed" to have, more like legacy ;-).

So the better objective would be to merge the man pages into the texinfo and extract/generate them from the texinfo, so that there is no duplication (and such that the command-line options are actually documented in the handbook!)

ng0

2019-02-14 13:56

developer   ~0013759

Sounds worse than what we have now.
I'd rather have duplication than having to generate manpages in a way which can break the build (texinfo writing: error prone, as proven many times here; groff, mdoc, etc: maybe error prone but not breaking the build).

Of course having duplication is bad.

Christian Grothoff

2019-02-14 14:10

manager   ~0013762

Ok, so we agree duplication is bad. IMO what we just need is to make it clear (and maybe even enforce via CI) that breaking the documentation build is just as bad as breaking the C build.

That, and of course 'make' targets that actually build the docs in all relevant ways ;-).

ng0

2019-02-14 14:17

developer   ~0013764

Yes. I've been trying to get this message through for a while. broken Texinfo means broken build in CI. It's as important as writing good C. It's not bad to commit bad Texinfo, but it is preferred to not break the build!

Christian Grothoff

2019-02-14 14:24

manager   ~0013766

Ok, so let's assume that message eventually resonates. Then what's wrong with transitioning to generating the man pages from Texinfo?

ng0

2019-02-14 14:37

developer   ~0013769

Nothing, but I have yet to see a generated man page which does not look like what help2man does. I'm not sure which projects could serve as an example to read into, because the majority of GNU seems to have gone the way of

man something
"help output here"
and if they put some thought into it after help2man:
>> "oh by the way read our info pages"

as a rough summary.

I don't think there's anything wrong with good manpages. There's everything wrong with generated manpages when they are approached like this.

Do you have any examples for what you were referring to?

Christian Grothoff

2019-02-14 14:44

manager   ~0013770

Nope, I just _remembered_ that GNU Hello generated the man page (not sure if it uses help2man), and I like the idea of de-duplication. Generating the man page by *combining* --help and hand-written stuff would seem ideal, as then we don't have to worry about options in man page not being consistent with options in the source. But you are right: I just had the rough idea, but did not look into the details, and there are certainly ways to make this go wrong and have terrible man pages (which would not be so good).

ng0

2019-02-14 14:56

developer   ~0013771

Okay, let's delay this and look into ways which could work for us with good outcomes before we decide on anything.

catonano

2019-02-22 07:13

reporter   ~0013931

can this be tagged 0.11.2 or 0.12 ?

Christian Grothoff

2019-02-22 17:25

manager   ~0013945

I'm not sure it is RC for either. As for 0.11.2, that one should be release when simply "enough interesting" bugs have been fixed, so tagging any one particular issue as RC is likely not ideal.

ng0

2019-02-22 17:34

developer   ~0013946

I veto on this one, as it will be most likely myself doing this work, and I don't think I have time to work on this for 0.11.1, .2, or 0.12 as there's too many other more important tasks to work on.

In my opinion It's a feature ticket. Whoever wants to work on this can work on it.

ng0

2019-02-22 17:35

developer   ~0013947

basically what Christian said. Unless someone steps up and does the work.

ng0

2019-02-28 14:38

developer   ~0014103

for reference: https://www.gnutls.org/manual/html_node/certtool-Invocation.html

ng0

2019-03-06 23:45

developer   ~0014160

I had the wrong take on this and understanding of roff/groff/mdoc and their implementations.

I have just imported a man page from Debian and spend some time editing it while also converting it to mdoc.
This is no problem for us (but I'm going to double check), as I'm going to describe in the documentation, as the tools understand a mostly matching set of their languages. In other words, it doesn't matter and it's really up to the writer. The writer being me for most of the recent edits in doc/man/ agrees that we will have more flexibility and can keep the man pages easier up to date with the texinfo approach we discussed, but for the time being mdoc is okay too.

ng0

2019-06-15 15:41

developer   ~0014555

Original issue is done (conversion to mdoc).

Issue History

Date Modified Username Field Change
2019-01-27 15:55 ng0 New Issue
2019-01-29 16:02 catonano Tag Attached: documentation
2019-02-14 12:12 Christian Grothoff Note Added: 0013752
2019-02-14 12:13 Christian Grothoff Status new => acknowledged
2019-02-14 13:56 ng0 Note Added: 0013759
2019-02-14 14:10 Christian Grothoff Note Added: 0013762
2019-02-14 14:17 ng0 Note Added: 0013764
2019-02-14 14:24 Christian Grothoff Note Added: 0013766
2019-02-14 14:37 ng0 Note Added: 0013769
2019-02-14 14:44 Christian Grothoff Note Added: 0013770
2019-02-14 14:56 ng0 Note Added: 0013771
2019-02-20 13:09 Christian Grothoff Severity minor => tweak
2019-02-20 13:10 Christian Grothoff Severity tweak => feature
2019-02-22 07:13 catonano Note Added: 0013931
2019-02-22 17:25 Christian Grothoff Note Added: 0013945
2019-02-22 17:34 ng0 Note Added: 0013946
2019-02-22 17:35 ng0 Note Added: 0013947
2019-02-28 14:38 ng0 Note Added: 0014103
2019-03-06 23:45 ng0 Note Added: 0014160
2019-06-05 19:01 Christian Grothoff Target Version => 0.11.6
2019-06-15 15:40 ng0 Assigned To => ng0
2019-06-15 15:40 ng0 Status acknowledged => assigned
2019-06-15 15:41 ng0 Status assigned => resolved
2019-06-15 15:41 ng0 Resolution open => fixed
2019-06-15 15:41 ng0 Fixed in Version => 0.11.6
2019-06-15 15:41 ng0 Note Added: 0014555