| 12 Aug 2022 |
| *  夜坂雅 | Yorusaka Miyabi wonders if there's any requirements for NixOS documentation to use DocBook. | 01:42:12 |
 pennae | pretty much everything except modules and the options we haven't touched yet use markdown as their primary format and just render to docbook as an intermediate format. some modules do that as well, albeit not automatically | 01:47:31 |
| 夜坂雅 | Yorusaka Miyabi | In reply to @pennae:matrix.eno.space
pretty much everything except modules and the options we haven't touched yet use markdown as their primary format and just render to docbook as an intermediate format. some modules do that as well, albeit not automatically I thought that, eventually all NixOS module option docstrings are written in CommonMark. | 02:55:24 |
| pennae | that's the plan :) | 02:56:11 |
| pennae | hope we'll get there for 22.11 | 02:56:18 |
| pennae | currently waiting for review on https://github.com/NixOS/nixpkgs/pull/185474 before we go any further | 02:57:00 |
| 夜坂雅 | Yorusaka Miyabi | In reply to @pennae:matrix.eno.space
currently waiting for review on https://github.com/NixOS/nixpkgs/pull/185474 before we go any further In this PR I found that there's a remaining part that looks like DocBook. 😅 | 03:34:59 |
| 夜坂雅 | Yorusaka Miyabi | This PR looks good to me. BTW, is lib.mdDoc a marker ? | 03:36:43 |
| pennae | it wraps the given text in a form make-options-doc recognizes as markdown so it can convert it to docbook, yes | 03:38:09 |
 John Ericson | https://github.com/NixOS/nix/pull/6877#issuecomment-1212877941 Eelco commented providing more details why he doesn't like the arch chapter, and seems to be anti having a reference | 17:02:06 |
| John Ericson | (I wrote that in the Nixpkgs arch chanel, but I meant to write that in this channel) | 17:03:02 |
| John Ericson | Based on our call yesterday, I think we all disagree with that? | 17:03:19 |
| John Ericson | so it would be good to do something as a team about that | 17:03:27 |
 tpw_rules | is there a way to automatically extract that stuff into something that's not doxygen? | 19:13:48 |
| John Ericson | tpw_rules: not in a good way | 19:27:28 |
| John Ericson | doxygen is is per defintion code decs | 19:27:39 |
| John Ericson | * doxygen is is per defintion code docs | 19:27:41 |
| John Ericson | there is no good way to get spec prose from that | 19:27:52 |
| tpw_rules | i was thinking more about the literate comment | 19:29:03 |
| pennae | ioo putting high-level docs in code is only any good for code bases that are structured like one would tell their story, and nix definitely isn't at this point | 19:32:25 |
 olaf | John Ericson: i am not opinionated about which repository docs go, as long as they go somewhere for a reason and the reasons gets documented (so we know for the future as well).
The statement that eelco "is anti having reference" is a bit broad.
It seems he believes that the nix documentation should be code reference.
But your work is spec reference. (can i say so?) | 22:51:26 |
| John Ericson | olaf: Sure, I would appreciate you seconding me it is spec reference not code reference | 22:52:42 |
| John Ericson | As to the repo, well I am pretty sure bottom half documentation does belong there, not top half documentation | 22:53:52 |
| John Ericson | I don't think he wants it elsewhere because then any keeping in sync problem would just get worse | 22:54:16 |
| John Ericson | and we can't require PRs that add new behavior also update the spec | 22:54:29 |
| pennae | how frequent are such PRs outside of explicitly experimental features? | 22:59:21 |
| pennae | for experimental stuff it's probably okay if well-written documentation lags behind the facts a bit, as long as the necessary information is there somewhere | 23:00:04 |
| 13 Aug 2022 |
| John Ericson | pennae: well most features should be experimental, I have a backlog of a few of them not sure what others got | 03:09:00 |
| John Ericson | A space that multiple implementations folllow I understand keeping separate | 03:09:22 |
| John Ericson | But I still rather start with that information in the manual | 03:10:07 |
