View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0005517 | GNUnet | documentation | public | 2019-01-27 15:55 | 2024-02-11 11:44 |
| Reporter | nikita | Assigned To | nikita | ||
| Priority | normal | Severity | feature | Reproducibility | have not tried |
| Status | closed | Resolution | fixed | ||
| Target Version | 0.11.6 | Fixed in Version | 0.11.6 | ||
| Summary | 0005517: man changes | ||||
| Description | We 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. | ||||
| Tags | No tags attached. | ||||
|
|
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!) |
|
|
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. |
|
|
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 ;-). |
|
|
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! |
|
|
Ok, so let's assume that message eventually resonates. Then what's wrong with transitioning to generating the man pages from Texinfo? |
|
|
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? |
|
|
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). |
|
|
Okay, let's delay this and look into ways which could work for us with good outcomes before we decide on anything. |
|
|
can this be tagged 0.11.2 or 0.12 ? |
|
|
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. |
|
|
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. |
|
|
basically what Christian said. Unless someone steps up and does the work. |
|
|
for reference: https://www.gnutls.org/manual/html_node/certtool-Invocation.html |
|
|
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. |
|
|
Original issue is done (conversion to mdoc). |
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2019-01-27 15:55 | nikita | 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 | nikita | Note Added: 0013759 | |
| 2019-02-14 14:10 | Christian Grothoff | Note Added: 0013762 | |
| 2019-02-14 14:17 | nikita | Note Added: 0013764 | |
| 2019-02-14 14:24 | Christian Grothoff | Note Added: 0013766 | |
| 2019-02-14 14:37 | nikita | Note Added: 0013769 | |
| 2019-02-14 14:44 | Christian Grothoff | Note Added: 0013770 | |
| 2019-02-14 14:56 | nikita | 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 | nikita | Note Added: 0013946 | |
| 2019-02-22 17:35 | nikita | Note Added: 0013947 | |
| 2019-02-28 14:38 | nikita | Note Added: 0014103 | |
| 2019-03-06 23:45 | nikita | Note Added: 0014160 | |
| 2019-06-05 19:01 | Christian Grothoff | Target Version | => 0.11.6 |
| 2019-06-15 15:40 | nikita | Assigned To | => nikita |
| 2019-06-15 15:40 | nikita | Status | acknowledged => assigned |
| 2019-06-15 15:41 | nikita | Status | assigned => resolved |
| 2019-06-15 15:41 | nikita | Resolution | open => fixed |
| 2019-06-15 15:41 | nikita | Fixed in Version | => 0.11.6 |
| 2019-06-15 15:41 | nikita | Note Added: 0014555 | |
| 2019-07-24 20:42 | Christian Grothoff | Status | resolved => closed |
| 2024-02-11 11:44 | Christian Grothoff | Tag Detached: documentation |
