From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 11192 invoked from network); 31 Aug 2020 20:51:34 -0000 Received: from alyss.skarnet.org (95.142.172.232) by inbox.vuxu.org with ESMTPUTF8; 31 Aug 2020 20:51:34 -0000 Received: (qmail 2347 invoked by uid 89); 31 Aug 2020 20:52:00 -0000 Mailing-List: contact supervision-help@list.skarnet.org; run by ezmlm Sender: Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Received: (qmail 2340 invoked from network); 31 Aug 2020 20:52:00 -0000 From: "Laurent Bercot" To: "supervision@list.skarnet.org" Subject: Re: [request for review] Port of s6 documentation to mdoc(7) Date: Mon, 31 Aug 2020 20:51:34 +0000 Message-Id: In-Reply-To: <20200831191433.wbjh6wltyqhdv5hl@mail.imca-cat.org> References: <877dtgtu1z.fsf@ada> <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org> <20200831191433.wbjh6wltyqhdv5hl@mail.imca-cat.org> Reply-To: "Laurent Bercot" User-Agent: eM_Client/8.0.3385.0 Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-VR-SPAMSTATE: OK X-VR-SPAMSCORE: 0 X-VR-SPAMCAUSE: gggruggvucftvghtrhhoucdtuddrgeduiedrudefhedgudehgecutefuodetggdotffvucfrrhhofhhilhgvmecupfgfoffgtffkveetuefngfdpqfgfvfenuceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkjghfrhgfgggtgfesthhqredttderjeenucfhrhhomhepfdfnrghurhgvnhhtuceuvghrtghothdfuceoshhkrgdqshhuphgvrhhvihhsihhonhesshhkrghrnhgvthdrohhrgheqnecuggftrfgrthhtvghrnhepvdfgveffueelgedvkedtffetgedvieeifeektefgueehffehleehjefhveeuieejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmohguvgepshhmthhpohhuth For the people who are not on #s6 and have missed the countless resurgences of this discussion, here is my position regarding documentation formats. I hope that by the end of this mail things are quite clear for everyone and I won't need to talk about this again,=20 ever. - Doc formats seem to be the #1 thing that's on people's minds, because it's a subject that keeps showing up *all the time*. To me, this is unfortunate; I wish people would spend more time on technical design discussions and be more curious about the internals of my software, and a bit less on surrounding things like how the documentation is written. (Yes, Guillermo, I will answer your mail. You should really join #s6 if possible, because I talked about the plans for s6-rc there; and I would also very much enjoy your precious willingness to talk software details.) - Everyone always has a lot of ideas on how things should go and what I should do. - Unfortunately, I have *zero* interest in doing those para-software things. I am interested in writing software that does stuff, not in spending my time learning a new rich text format and rewriting documentation. The time I am willing to devote to free software is best employed actually writing code, not doing things I hate. Writing doc is enough of a chore as is; it needs to be as easy as possible for me, without any additional hurdle getting in the way. - And that should really be no big deal. There is a whole community interested in s6 documentation, and making man pages, etc., and who always sounds very enthusiastic. So, it should be easy to find people who are willing to invest some time and do the thing the community=20 wants, right? - For some reason, it turns out that it's not that easy. Somehow, the people who always have a lot of ideas are nowhere to be found when I try to delegate the work. - This pattern has been replicating for a long while now, and it has made me quite jaded, to the point that I now lose patience very quickly whenever documentation formats are mentioned, and I sometimes cannot=20 help answering with a jab at the end. - Alexis' contribution is, literally, one-of-a-kind: someone wanted a thing to be done *and did it themself*. That is something I respect, something that has a lot of value to me, and I want to make that work useful. - Yes, it would be better to have One Single Source Of Truth, rather than duplication of information. I totally agree on the principle. However, as of now, the limiting factor is *not* the consistency checks between two sets of documentation. It is the amount of human time that is voluntarily dedicated to the task of providing said documentation. Talking about the N+1 ways of getting One Source Of Truth and generating several backend documentation formats accomplishes nothing. I know about DocBook; by now, I know about every single freaking documentation format and toolchain in existence, and about every single possible workflow I could use. That does not change the fact that it would be more burden placed on me, that I have no intention of taking. - scdoc is, in a way, an exception: ddv and I had a long talk, the scdoc format is simple enough, the toolchain is good quality, I have no objection to writing new documentation in scdoc. (Emphasis on new; existing doc will have to be converted by someone else than me. Or I could be paid to do it.) The problem is that at the moment it does not produce HTML, and post- processing the roff output produces horrible, ugly HTML, so it's not an acceptable solution. So, for now, scdoc is not usable for the purpose of a multi-format s6 documentation. But if it grows a decent HTML engine, it will be. - What we have with Alexis' work is two sources of truth, that will have to be kept in sync, but that's work they're willing to do - it's the first thing I asked - and that will make the community happy, that will improve on the current situation. If maintaining the set of man pages in sync with the official documentation reveals itself to be unsustainable, *then* will be the time to do something about it. - Unless, of course, someone comes up with the perfect solution (adding a DocBook dependency is not a perfect solution, and neither is generating HTML from mandoc), in which case, obviously, they would have the time and willingness to do all the necessary work themself, and in doing so, actually meaningfully contribute to the community instead of only adding their drop to the useless sea of It's Easy You Just Have To Do This, Just Saying In Case You Had Not Considered. -- Laurent