* [9front] 9front man pages @ 2024-03-08 4:47 eso 2024-03-08 5:07 ` Jacob Moody 2024-03-08 5:23 ` ori 0 siblings, 2 replies; 21+ messages in thread From: eso @ 2024-03-08 4:47 UTC (permalink / raw) To: 9front I would like to improve 9front's documentation. We all know it's not great. But those who are in the best position to rewrite them (those most knowledgeable) see it as not worth their time, which is more than justified. I am not a computer science professional, I'm just a writer. Technology is a hobby for me. I cannot write you a filesystem, but maybe I can write the documentation for it? I'm willing to try and rewrite the documentation, and I can occasionally check in with the heavy hitters to see if I'm straight. But first I want to get some feedback on the objectives of a man page redux. - Runtime options are listed for readability, like OpenBSD. You shouldn't have to grep for the most basic information. - Explanations of software usage should represent a typical 9front user setup. You could argue that'd be a standalone machine, but I think the appropriate model would be a local fs+auth server. No more Bell Labs examples. None of us have that many gateways and nameservers. Nobody has a gnot terminal. Nobody has a jukebox. And who is emelie? This would be most relevant to section 8, system administration. - Usage examples should not be exhaustive, but should cover the most well-tread paths as far as usage. The first tar(1) man page example should be extracting a tarball, because that’s what most people use tar for day-to-day. And if you can imagine a crazy world where you aren't a powerful technomancer, and thus don't have the tar options memorized, you could imagine that would be what you'd go looking for in the manual if you weren't sure. A dd(1) example should be something like cloning drives, something people often use dd for. I'd like to hear what others think. Also I was thinking this would just cover system usage sections like userland, system administration, file servers, etc. But if it goes well, maybe we can go beyond that. The last patch I submitted, for acmed(8), Ori had some objections about my phrasing. So it seems I could use some advisement. But for the record, I have experience with technical writing. My Best, Verbose ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 4:47 [9front] 9front man pages eso @ 2024-03-08 5:07 ` Jacob Moody 2024-03-08 5:28 ` Roberto E. Vargas Caballero 2024-03-08 5:23 ` ori 1 sibling, 1 reply; 21+ messages in thread From: Jacob Moody @ 2024-03-08 5:07 UTC (permalink / raw) To: 9front On 3/7/24 22:47, eso@self.rodeo wrote: > I would like to improve 9front's documentation. We all know it's not > great. But those who are in the best position to rewrite them (those > most knowledgeable) see it as not worth their time, which is more than > justified. I am not a computer science professional, I'm just a writer. > Technology is a hobby for me. I cannot write you a filesystem, but maybe > I can write the documentation for it? > I'm willing to try and rewrite the documentation, and I can occasionally > check in with the heavy hitters to see if I'm straight. But first I want > to get some feedback on the objectives of a man page redux. > - Runtime options are listed for readability, like OpenBSD. You > shouldn't have to grep for the most basic information. > - Explanations of software usage should represent a typical 9front user > setup. You could argue that'd be a standalone machine, but I think the > appropriate model would be a local fs+auth server. No more Bell Labs > examples. None of us have that many gateways and nameservers. Nobody has > a gnot terminal. Nobody has a jukebox. And who is emelie? This would be > most relevant to section 8, system administration. > - Usage examples should not be exhaustive, but should cover the most > well-tread paths as far as usage. The first tar(1) man page example > should be extracting a tarball, because that’s what most people use tar > for day-to-day. And if you can imagine a crazy world where you aren't a > powerful technomancer, and thus don't have the tar options memorized, > you could imagine that would be what you'd go looking for in the manual > if you weren't sure. A dd(1) example should be something like cloning > drives, something people often use dd for. This would be touching the artwork for me honestly. I personally love some of those more historical examples(Kremvax is my favorite). I think our manual pages overall are pretty great and I don't think the examples need to be min-maxed for most common deployment. We're here to have some fun as well. I am also not sure what you mean by "Runtime options are listed for readability", do you mean to have a table layout for all command line options consistently? If so I also would not personally be a fan of that. > > I'd like to hear what others think. Also I was thinking this would just > cover system usage sections like userland, system administration, file > servers, etc. But if it goes well, maybe we can go beyond that. The last > patch I submitted, for acmed(8), Ori had some objections about my > phrasing. So it seems I could use some advisement. But for the record, I > have experience with technical writing. I think what you want would be better suited to something besides the manual pages. It sounds like a majority of your grips are with examples. Maybe you could make a git repo full of examples, or perhaps something for the wiki or the fqa. If you feel strongly about some manual page examples I'd say point those out specifically and we can discuss specific replacements and examples, but a more general "modernize the manpage examples" is going to be hard to agree to. Just my 2 cents. Thanks, moody ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 5:07 ` Jacob Moody @ 2024-03-08 5:28 ` Roberto E. Vargas Caballero 2024-03-08 9:01 ` qwx 0 siblings, 1 reply; 21+ messages in thread From: Roberto E. Vargas Caballero @ 2024-03-08 5:28 UTC (permalink / raw) To: 9front Hi, On Thu, Mar 07, 2024 at 11:07:14PM -0600, Jacob Moody wrote: > I am also not sure what you mean by "Runtime options are listed for > readability", do you mean to have a table layout for all command line > options consistently? If so I also would not personally be a fan of that. I agree with Moody here. The 9front man pages are written from the point of view of a full lecture of the page, giving a good organization of the text and relating options between them. Moving to have a table of options will enforce a bad documentation culture where the full overall reason of the options is lost because they are dealt individually. I think the SYNOPSIS section is already providing a good summary. > > I'd like to hear what others think. Also I was thinking this would just > > cover system usage sections like userland, system administration, file > > servers, etc. But if it goes well, maybe we can go beyond that. The last > > patch I submitted, for acmed(8), Ori had some objections about my > > phrasing. So it seems I could use some advisement. But for the record, I > > have experience with technical writing. > > I think what you want would be better suited to something besides the manual > pages. It sounds like a majority of your grips are with examples. Maybe you > could make a git repo full of examples, or perhaps something for the wiki or > the fqa. > > If you feel strongly about some manual page examples I'd say point those out > specifically and we can discuss specific replacements and examples, but a more > general "modernize the manpage examples" is going to be hard to agree to. Indeed. I think there are more important problems with man pages currently, like for example some pages that don't give enough context, pages that miss important limitations or hidden knowledge, or pages that are clearly outdated. Regards, ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 5:28 ` Roberto E. Vargas Caballero @ 2024-03-08 9:01 ` qwx 2024-03-08 11:30 ` hiro 0 siblings, 1 reply; 21+ messages in thread From: qwx @ 2024-03-08 9:01 UTC (permalink / raw) To: 9front On Fri Mar 8 06:28:55 +0100 2024, k0ga@shike2.com wrote: > Hi, > > On Thu, Mar 07, 2024 at 11:07:14PM -0600, Jacob Moody wrote: > > I am also not sure what you mean by "Runtime options are listed for > > readability", do you mean to have a table layout for all command line > > options consistently? If so I also would not personally be a fan of that. > > I agree with Moody here. The 9front man pages are written from the point > of view of a full lecture of the page, giving a good organization of the > text and relating options between them. Moving to have a table of options > will enforce a bad documentation culture where the full overall reason of > the options is lost because they are dealt individually. I think the > SYNOPSIS section is already providing a good summary. This has been argued over before and I personally disagree with the notion of having to read the entire manpage just to find the one flag I'm interested in. I would much prefer (with much bias) the style/format in ipconfig(8) or wadfs(4), combining both. Then again that's simply not practical in some cases, so as Ori said it should be dealt on a case by case basis. On Fri Mar 8 05:47:24 +0100 2024, eso@self.rodeo wrote: > I'd like to hear what others think. Also I was thinking this would just > cover system usage sections like userland, system administration, file > servers, etc. But if it goes well, maybe we can go beyond that. The last > patch I submitted, for acmed(8), Ori had some objections about my > phrasing. So it seems I could use some advisement. But for the record, I > have experience with technical writing. I think there's no point in trying to come up with a general directive which everyone agrees on; just between us with Ori, moody and k0ga, we agree on most points, but not all. I suggest that you just pick manpages you would like to improve, and write a patch, so something more specific could be discussed. Cheers, qwx ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 9:01 ` qwx @ 2024-03-08 11:30 ` hiro 2024-03-08 11:34 ` hiro 0 siblings, 1 reply; 21+ messages in thread From: hiro @ 2024-03-08 11:30 UTC (permalink / raw) To: 9front "We all know it's not great" This is the second sentence in this thread. Yeah, do we then? How do you know? ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 11:30 ` hiro @ 2024-03-08 11:34 ` hiro 2024-03-08 11:35 ` hiro 2024-03-08 16:01 ` eso 0 siblings, 2 replies; 21+ messages in thread From: hiro @ 2024-03-08 11:34 UTC (permalink / raw) To: 9front Also, generally, I think *not* having a disparate "documentation team" is a feature, so far. I prefer it when people change code (and relevant documentation) gradually. If you add a new feature, this will require obvious additions to the documentation. If this entitles you to touch the documentation anyways, I understand you might rework the surrounding sentences slightly to make more sense. But redoing everything from the ground up is not something we generally do here just for the sake of keeping busy. If the documentation has a bug, send a patch. People regularly make errors, forget things, etc. But keep the changes minimal. ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 11:34 ` hiro @ 2024-03-08 11:35 ` hiro 2024-03-08 16:01 ` eso 1 sibling, 0 replies; 21+ messages in thread From: hiro @ 2024-03-08 11:35 UTC (permalink / raw) To: 9front verbose is a real name, or an attribute? ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 11:34 ` hiro 2024-03-08 11:35 ` hiro @ 2024-03-08 16:01 ` eso 2024-03-08 16:24 ` qwx 1 sibling, 1 reply; 21+ messages in thread From: eso @ 2024-03-08 16:01 UTC (permalink / raw) To: 9front Hiro: > Redoing everything from the ground up is not something we generally > do here just for the sake of keeping busy I was not thinking of a ground-up kind of thing. Just a pass-through with the ideas in my original email in mind. > Yeah, do we then? How do you know? I'm sorry for the ambiguity. By "not great" I do not mean "bad" but just not great, excellent, exceptional. I was talking with 9fans the day before and I got the feeling that "needs improvement" was an apt consensus from all those I spoke with. But I apologize for projecting my narrow slice of perspective on the larger community. > verbose is a real name, or an attribute? Both. Moody: > This would be touching the artwork for me honestly. I personally love > some of those more historical examples(Kremvax is my favorite). I appreciate this perspective. It will not be ignored. > our manual pages overall are pretty great and I don't think the > examples > need to be min-maxed for most common deployment. We're here to have > some > fun as well. My perspective is simply that the purpose of manuals should be to help the users. I don't think you need to redact kremvax or rewrite the docs to do that, but in my opinion there is some room for improvement. > I think what you want would be better suited to something besides the > manual > pages. It sounds like a majority of your grips are with examples. Maybe > you > could make a git repo full of examples, or perhaps something for the > wiki or > the fqa. I would like that actually, I can do this in supplement to whatever work on the manuals gets done. And having this supplementary resource in mind would keep more examples and explanation out of the man pages, which is something others have expressed concern over. > If you feel strongly about some manual page examples I'd say point > those out > specifically and we can discuss specific replacements and examples, but > a more > general "modernize the manpage examples" is going to be hard to agree > to. See next quote... Ori: > I'd just suggest going one manpage at a time, and getting feedback > as you go; you'll probably get a feel for what the docs should be as > we discuss. There's a lot to improve, but I think you'll find there's > a lot we quite like about the current style. I'm going to move forward with this. My initial email was trying to get some feedback before I start sending patches, and I've gotten plenty. So I will start sending patches. And I will lose the mentality of a grand effort. Sorry, I am naturally a more idealist head-in-the-clouds kind of person which I understand is inappropriate for this project. > I think we could use more examples, but I don't think we > should turn manpages into tutorials. I agree, that's what I meant by "Usage examples should not be exhaustive." I do value tutorials, but those should stay out of the manuals. > I think the biggest missing thing in the 9front documentation > is is a set of "theory of operation" type documents that sit > between manpages and the fqa, and walk through how the pieces > of the system are meant to interact. I agree. Roberto: > I think there are more important problems with man pages currently, > like for example some pages that don't give enough context, pages that > miss important limitations or hidden knowledge, or pages that are > clearly > outdated. I'm not in the best position to fill in hidden information, but I think the limitations and context are in the same vein as what Ori said above. qwx: > just pick manpages you would like to improve, and write a patch, > so something more specific could be discussed. Will do. People seem very split on the table of flags vs how it is currently. I'll give others more time to discuss that, and focus on lower hanging fruit in the mean time. Thanks for your messages, and apologies if my formatting is crap, since I'm doing it manually without knowing how wide 80 columns actually is on this email client. Just eyeballing it. Anyways, happy Friday. verbose ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 16:01 ` eso @ 2024-03-08 16:24 ` qwx 0 siblings, 0 replies; 21+ messages in thread From: qwx @ 2024-03-08 16:24 UTC (permalink / raw) To: 9front On Fri Mar 8 17:02:32 +0100 2024, eso@self.rodeo wrote: > Thanks for your messages, and apologies if my formatting > is crap, > since I'm doing it manually without knowing how wide 80 columns actually > is on > this email client. Just eyeballing it. Anyways, happy Friday. Just a tip, but you can use fmt(1) for this. My F [1] rc script starts hold(1) then formats the text I typed in when I end it and pushes that to the snarf buffer so I can directly paste it in nedmail(1). I'm certain others have better approaches as well. Cheers, qwx [1] http://shithub.us/qwx/rc/HEAD/bin/F/raw ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 4:47 [9front] 9front man pages eso 2024-03-08 5:07 ` Jacob Moody @ 2024-03-08 5:23 ` ori 2024-03-08 17:40 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 1 sibling, 1 reply; 21+ messages in thread From: ori @ 2024-03-08 5:23 UTC (permalink / raw) To: 9front Overall, this sounds reasonable to me (though I'd argue that 9front docs are pretty good, there's certainly room to improve them). I'd just suggest going one manpage at a time, and getting feedback as you go; you'll probably get a feel for what the docs should be as we discuss. There's a lot to improve, but I think you'll find there's a lot we quite like about the current style. Quoth eso@self.rodeo: > I would like to improve 9front's documentation. We all know it's not > great. But those who are in the best position to rewrite them (those > most knowledgeable) see it as not worth their time, which is more than > justified. I am not a computer science professional, I'm just a writer. > Technology is a hobby for me. I cannot write you a filesystem, but maybe > I can write the documentation for it? I disagree. There's room to improve, but I think the system is relatively well docuemnted. It also seems that we do think it's worth our time, but nobody has stepped forward to do a thorough review. If you want to do that, this would be welcome. > I'm willing to try and rewrite the documentation, and I can occasionally > check in with the heavy hitters to see if I'm straight. But first I want > to get some feedback on the objectives of a man page redux. > - Runtime options are listed for readability, like OpenBSD. You > shouldn't have to grep for the most basic information. I'm assuming by this, you mean a table of flags? I'm in favor of that. > - Explanations of software usage should represent a typical 9front user > setup. You could argue that'd be a standalone machine, but I think the > appropriate model would be a local fs+auth server. No more Bell Labs > examples. None of us have that many gateways and nameservers. Nobody has > a gnot terminal. Nobody has a jukebox. And who is emelie? This would be > most relevant to section 8, system administration. "typical" varies, but we can discuss on a case by case basis. > - Usage examples should not be exhaustive, but should cover the most > well-tread paths as far as usage. The first tar(1) man page example > should be extracting a tarball, because that’s what most people use tar > for day-to-day. And if you can imagine a crazy world where you aren't a > powerful technomancer, and thus don't have the tar options memorized, > you could imagine that would be what you'd go looking for in the manual > if you weren't sure. A dd(1) example should be something like cloning > drives, something people often use dd for. > I think we could use more examples, but I don't think we should turn manpages into tutorials. > I'd like to hear what others think. Also I was thinking this would just > cover system usage sections like userland, system administration, file > servers, etc. But if it goes well, maybe we can go beyond that. The last > patch I submitted, for acmed(8), Ori had some objections about my > phrasing. So it seems I could use some advisement. But for the record, I > have experience with technical writing. > I think the biggest missing thing in the 9front documentation is is a set of "theory of operation" type documents that sit between manpages and the fqa, and walk through how the pieces of the system are meant to interact. I attempted something in that style here: https://wiki.9front.org/upas-theory ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 5:23 ` ori @ 2024-03-08 17:40 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 2024-03-08 18:30 ` hiro 0 siblings, 1 reply; 21+ messages in thread From: Lyndon Nerenberg (VE7TFX/VE6BBM) @ 2024-03-08 17:40 UTC (permalink / raw) To: 9front My biggest concern with these sort of well meant attempts to help with documentation is this: Writing *good* documentation about a piece of software requires you to have an intimate understanding of that software, down to its core. Without that, you will make mistakes. And quite often what sets apart an amazing manpage from a good one is how it expresses the subtleties of the software it is describing. That requires a deep understanding of the subject matter. For the most part, the Plan 9 manpages are well written as they stand. A few suffer from ESL syndrome and could use some copy editing to remove ambiguity. But a wholesale drive-by edit of everything is wrong, IMO. My major gripe with all the manpages is how the options are documented. I will disagree with Rob Pike until the day I die that they should be described in-line as they currently are. Just like he has red-green colour blindness problems, I suffer from diplopia (very bad double vision) that makes spotting those flag definitions nearly impossible. I firmly believe options should be explicitly called out in a single section in tagged paragraph form (i.e. the idiomatic format used in all the BSD manpages). But that's a bikeshed for another day. In summary, I encourage you to find ways to contribute to the community. If you want to help with documentation, I would start out by picking one or two manpages you feel need an update, then proposing your changes. I suspect you will learn a lot from the ensuing discussion. There is a lot of history behind the style and conventions used; you can't ignore that. --lyndon ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 17:40 ` Lyndon Nerenberg (VE7TFX/VE6BBM) @ 2024-03-08 18:30 ` hiro 2024-03-08 23:20 ` umbraticus 0 siblings, 1 reply; 21+ messages in thread From: hiro @ 2024-03-08 18:30 UTC (permalink / raw) To: 9front > impossible. I firmly believe options should be explicitly called > out in a single section in tagged paragraph form (i.e. the idiomatic > format used in all the BSD manpages). But that's a bikeshed for > another day. they are. in the source-code. ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 18:30 ` hiro @ 2024-03-08 23:20 ` umbraticus 2024-03-08 23:50 ` ori 0 siblings, 1 reply; 21+ messages in thread From: umbraticus @ 2024-03-08 23:20 UTC (permalink / raw) To: 9front > they are. in the source-code. indeed. you could have a tool called usage that greps for lines like case 'f': /* explanation of f flag */ within ARGBEGIN{}ARGEND, with a matching style convention. and whatever the equivalent for rc scripts is. or maybe src(1) is good enough. umbraticus ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 23:20 ` umbraticus @ 2024-03-08 23:50 ` ori 2024-03-09 0:40 ` sl 0 siblings, 1 reply; 21+ messages in thread From: ori @ 2024-03-08 23:50 UTC (permalink / raw) To: 9front Quoth umbraticus@prosimetrum.com: > > they are. in the source-code. > > indeed. you could have a tool called usage that greps for lines like > > case 'f': /* explanation of f flag */ > > within ARGBEGIN{}ARGEND, with a matching style convention. > > and whatever the equivalent for rc scripts is. > > or maybe src(1) is good enough. > > umbraticus We could also add a semantic tag to the manpage macro set for tags, so they render inline, but can be found with some tool. The flag .FL -a sends all output to stderr and the flags can be indexed/searched from this. wtf grep -a (wtf, of course, stands for 'whats the flag') ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-08 23:50 ` ori @ 2024-03-09 0:40 ` sl 2024-03-09 1:08 ` hiro 0 siblings, 1 reply; 21+ messages in thread From: sl @ 2024-03-09 0:40 UTC (permalink / raw) To: 9front some questions: - why are the man pages the way they are - which ones are new to 9front some answers: - one of the aims of the original authors was to keep the man pages short, preferrably to one page, if possible. - we've imported or added a lot of new stuff, many of the man pages that appeared alongside that new stuff either disregarded or never promised to adhere to the intentions of plan 9's original authors. some suggestions: - i agree, evaluating one page at a time is the only way forward. read and edit for content, but only if necessary. - i prefer the "table of flags" approach, myself, but have been rebuffed on this point in the past. there is no consensus, so it is what it is. i like ori's suggestion of creating a special macro, but then that implies a massive effort to update every single man page that features flags, and some mechanism for enforcing its use in future (otherwise the effort would be kind of useless), both of which seem unlikely to happen. - "read the source" as an alternative to documenting flags seems to obviate the need for man pages at all, which is quite a bit more radical than editing the man pages that already exist. probably the source and the man pages should be arranged to compliment each other, since neither can really replace the other's intended function. - uriel's suggestion way back when to dive into editing man pages as a way of contributing when you don't know how to do anything else was more geared towards spellcheck and grammar, if i understood him correctly. early in my plan 9 career i stumbled over pretty much this same debate. there was even an argument to omit some debug flags i unearthed because if we documented them then we would have to maintain them (or so the argument went). sl ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-09 0:40 ` sl @ 2024-03-09 1:08 ` hiro 2024-03-09 1:36 ` Stanley Lieber 0 siblings, 1 reply; 21+ messages in thread From: hiro @ 2024-03-09 1:08 UTC (permalink / raw) To: 9front since you bring up uriel, the requirement to edit the man page should obviously be to have first studied strunk&white's for any aspiring editor. ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-09 1:08 ` hiro @ 2024-03-09 1:36 ` Stanley Lieber 2024-03-09 11:01 ` sirjofri 0 siblings, 1 reply; 21+ messages in thread From: Stanley Lieber @ 2024-03-09 1:36 UTC (permalink / raw) To: 9front On March 8, 2024 8:08:04 PM EST, hiro <23hiro@gmail.com> wrote: >since you bring up uriel, the requirement to edit the man page should >obviously be to have first studied strunk&white's for any aspiring >editor. > and dr slump in the original catalan (rip toriyama san). sl ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-09 1:36 ` Stanley Lieber @ 2024-03-09 11:01 ` sirjofri 2024-03-10 19:16 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 0 siblings, 1 reply; 21+ messages in thread From: sirjofri @ 2024-03-09 11:01 UTC (permalink / raw) To: 9front Hi all, as one who did some man page editing earlier and who likes writing documentation in general, I also have to raise my voice at some point. I personally see two use cases for man pages, both are drastically different: (1) You read a man page to understand how a program is working and how you should use it. For this use case it's important to read the man page, not only skim for arguments. Of course, some details can still be in the list/table layout, for example all the flags and attributes for print(2). For this use case, I also prefer to have most things as prose, only to prevent new people from using the program before reading the man page thoroughly (users tend to pick the flags, run the program, and wonder why nothing works, only to ask other users who can respond with rtfm). (2) If you already know how a program works and how to use it, but you just want to know about a single flag or something. In this case, you usually don't want to read a full book, a simple list with description is often enough. I don't think the man pages as they currently are fit both use cases to perfection, and I don't think they can. We have docs that are more towards (1) (or even surpassing that case), and some programs have a usage function which is just too little for (2). I like the idea of having an additional .FL troff macro for flags, though I think it's still impossible to get a good format using it, because of the nature of how the man pages are written. It can be much easier to find the flag though. I also like the idea of having an additional program that parses the source file for everything in between ARGBEGIN/ARGEND, combined with comments for description. Flags without comment could be omitted to have the option of omitting debug functionality, and it's easy enough to document with that. On the other hand, that puts part of the documentation into the source code, which is very much different from how man pages work. I would probably use both solutions, but both are a lot of work on existing files. Regarding the flag macro, I think it's still a question of how to use it. Page can't jump to a specific line, and how would you parse the whole thing? The naive solution would probably be to only print this paragraph, or (in case of troff) highlight it differently in some case to make it easier to find. I would certainly help edit the man pages to fit the new scheme, and I'd also help adjust the comments in ARGBEGIN/ARGEND as far as I can. I can also write a src-like program that extracts the details from the programs (wtf), but that's probably so trivial that any developer could do that. Another point that ori mentioned: the theory of how things work. I see that there's lots of stuff missing in that regard. It would certainly be nice to have some documents in the sense of /sys/doc, though I can perfectly see that we don't want to change the historical artwork there and clutter it with thousands of modern pages. I can imagine some separate repo for that (similar to how fqa is separate), something that can be seen as a part of the system, but is separate. On the other hand, we won't have too much so we could as well include it into /sys/doc, extending the historical artwork. Nevertheless, the biggest issue is: who's gonna write all that? It's a lot of work. I know there's the wiki, but tbh many people don't know about it, and the quality is ... varying. Also, the current implementation is very flat (unlike wikifs), so it's also hard to structure it in the sense of what's commonly known as a wiki. sirjofri ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-09 11:01 ` sirjofri @ 2024-03-10 19:16 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 2024-03-10 21:05 ` sirjofri 2024-03-10 21:11 ` hiro 0 siblings, 2 replies; 21+ messages in thread From: Lyndon Nerenberg (VE7TFX/VE6BBM) @ 2024-03-10 19:16 UTC (permalink / raw) To: 9front, sirjofri sirjofri writes: > I also like the idea of having an additional program that parses the source f > ile for everything in between ARGBEGIN/ARGEND, combined with comments for des > cription. Flags without comment could be omitted to have the option of omitti > ng debug functionality, and it's easy enough to document with that. On the ot > her hand, that puts part of the documentation into the source code, which is > very much different from how man pages work. The trouble with this approach is it only works with the languages it knows about. What if I write something in Fortran? Or Go? Or whatever other language I port across. Whatever this is, it needs to be universal, and I don't see a practical solution. I don't really believe the argument that people will read only the flags documentation and ignore the manpage. Someone that lazy is likely not reading the manpage at all. And anyway, that argument is purely speculation. Whenever you read technical documentation, those sorts of enumerated lists are almost always called out separately. There are several reasons for that, readablilty being paramount. While I'm a firm believer in precedent, it's shouldn't be cast in granite. I firmly believe documenting command flags inline was a mistake. We should be able to admit that and fix it. --lyndon ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-10 19:16 ` Lyndon Nerenberg (VE7TFX/VE6BBM) @ 2024-03-10 21:05 ` sirjofri 2024-03-10 21:11 ` hiro 1 sibling, 0 replies; 21+ messages in thread From: sirjofri @ 2024-03-10 21:05 UTC (permalink / raw) To: 9front 10.03.2024 20:18:25 Lyndon Nerenberg (VE7TFX/VE6BBM) <lyndon@orthanc.ca>: > sirjofri writes: > >> I also like the idea of having an additional program that parses the source f >> ile for everything in between ARGBEGIN/ARGEND, combined with comments for des >> cription. Flags without comment could be omitted to have the option of omitti >> ng debug functionality, and it's easy enough to document with that. On the ot >> her hand, that puts part of the documentation into the source code, which is >> very much different from how man pages work. > > The trouble with this approach is it only works with the languages > it knows about. > > What if I write something in Fortran? Or Go? Or whatever other > language I port across. Whatever this is, it needs to be universal, > and I don't see a practical solution. That's a valid point. I was also briefly thinking about rc programs, and that has the same problem, basically (although we have a standard there). > I don't really believe the argument that people will read only > the flags documentation and ignore the manpage. Someone that lazy > is likely not reading the manpage at all. And anyway, that argument > is purely speculation. > > Whenever you read technical documentation, those sorts of enumerated > lists are almost always called out separately. There are several > reasons for that, readablilty being paramount. I also sometimes see man pages with both practices on the same page. While one part discussed the arguments inline, another section has a list/table of arguments that's suitable for a look-up table. That would of course lengthen the man pages, but also be helpful. I often find myself looking for all the print(2) arguments. I know how print works, so I don't need all the page, but the table only. Sometimes it would be nice to just open that part of the page and skip everything else, but there can't be a single solution for everything. > While I'm a firm believer in precedent, it's shouldn't be cast in > granite. I firmly believe documenting command flags inline was a > mistake. We should be able to admit that and fix it. I don't believe it's a mistake. I think "mistake" is a strong word for decisions like that. I'm sure the inventors invested lots of thought and discussion to get to this decision, although it doesn't seem like that in the modern light. Coming from a hypertext perspective, the format of the content is never "correct" for all use cases. You can present something as a list, as paragraphs, as a table, as a guided tour or even graphics. Just ask ChatGPT to tell you about the command line flags written as a poem. Useful? Probably not at all. Though that discussion leads to nothing and I know people don't like AI (for reasons). Better find a way to write documentation that helps most people in most cases. sirjofri ^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [9front] 9front man pages 2024-03-10 19:16 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 2024-03-10 21:05 ` sirjofri @ 2024-03-10 21:11 ` hiro 1 sibling, 0 replies; 21+ messages in thread From: hiro @ 2024-03-10 21:11 UTC (permalink / raw) To: 9front > While I'm a firm believer in precedent, it's shouldn't be cast in > granite. I firmly believe documenting command flags inline was a > mistake. We should be able to admit that and fix it. i don't need to admit anything that isn't true. and btw, if you're bored... there's enough other more important things to fix, work on. ^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2024-03-10 21:12 UTC | newest] Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2024-03-08 4:47 [9front] 9front man pages eso 2024-03-08 5:07 ` Jacob Moody 2024-03-08 5:28 ` Roberto E. Vargas Caballero 2024-03-08 9:01 ` qwx 2024-03-08 11:30 ` hiro 2024-03-08 11:34 ` hiro 2024-03-08 11:35 ` hiro 2024-03-08 16:01 ` eso 2024-03-08 16:24 ` qwx 2024-03-08 5:23 ` ori 2024-03-08 17:40 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 2024-03-08 18:30 ` hiro 2024-03-08 23:20 ` umbraticus 2024-03-08 23:50 ` ori 2024-03-09 0:40 ` sl 2024-03-09 1:08 ` hiro 2024-03-09 1:36 ` Stanley Lieber 2024-03-09 11:01 ` sirjofri 2024-03-10 19:16 ` Lyndon Nerenberg (VE7TFX/VE6BBM) 2024-03-10 21:05 ` sirjofri 2024-03-10 21:11 ` hiro
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).