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.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,FREEMAIL_FROM,MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 8659 invoked from network); 1 Sep 2020 11:55:30 -0000 Received: from alyss.skarnet.org (95.142.172.232) by inbox.vuxu.org with ESMTPUTF8; 1 Sep 2020 11:55:30 -0000 Received: (qmail 17633 invoked by uid 89); 1 Sep 2020 11:55:56 -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 17626 invoked from network); 1 Sep 2020 11:55:56 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=references:user-agent:from:to:subject:in-reply-to:date:message-id :mime-version; bh=NowfHABNNF+2wrLVqz/wFIhAi4ubQdIoLICOus64BU0=; b=ib9u6q4d/tYVULV8bw1ulEzVcOdvnraq44TxZ2aS2nWfVCj+lxcjgd5JJRfer0dnKr r+TMQgk7Pb1FCwjJ0waPfRPG09ciHt3E4tTM9VKRKWKJu7AKQP4MUCE817J/u1/8Owfz yu/FPHCNaetA/fIBKs3S4OdTX1W6+3a/RMHl9KaOJCQEnsbv8gkdz2RdCE/JWJ6W+AOI QxMSuMpaBtcaCh5bmfJpA8Yf+BHeu0KFsi38X1sAFeXM88ndIdCqlJ/D8oKc2CsyGV0F rhkjCY0wcG+HxTQNz3PYmEO2Z1OIsk4qmrFSYh7+ehlR4yu4SP0H2EFLAtnXMqxNUsTQ T23A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:references:user-agent:from:to:subject :in-reply-to:date:message-id:mime-version; bh=NowfHABNNF+2wrLVqz/wFIhAi4ubQdIoLICOus64BU0=; b=LA9hRBKpajXeOsYphvUD9baoJN6FtzaI/p1tTS3TLQSosDqtoXjus6Td0QFttqiJPU 5kZVE9yEVUxhP+C2xhZ00Zrn4Ebfqv3pM2DMrFHIpz0AvPeL401qRSF5XJREcP6T9JOi X3v1BrpHxmQG3rT6ZXM2HjIVPkWrFnjYIiApfgzL4lSXwGA2pr/NGntgQsLOn9WrTR6+ IDDcUJMSUPz5/VwXs4pYW+/DpZsCEHtZYxJqceOTMObrkMXw3R8yKVZDNTZD1KwM9gvR 7P36fhUeYXTMme7hI/XUQyU1uphdUo53BOyMX0LB6yuI33yonu87JLyeivfgUgjRkAEo xfOQ== X-Gm-Message-State: AOAM5332XJg2s/xvXu/hZZ4LjadI544W2YzUFEQW1CGBXMTeTzKajJOa 7ivsWTkBKu8RsE/MQ1kVIMgvrZLjbpU= X-Google-Smtp-Source: ABdhPJy3TK9QQFjXBPMyci1iDVTIi9TksN4TW0SNO7y+jnLjCxTLgK1o0KohsZRBwKGgQHRarXD1hg== X-Received: by 2002:a17:90a:9d82:: with SMTP id k2mr1250701pjp.197.1598961327734; Tue, 01 Sep 2020 04:55:27 -0700 (PDT) References: <877dtgtu1z.fsf@ada> <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org> <20200831191433.wbjh6wltyqhdv5hl@mail.imca-cat.org> <20200901063801.GA2158@caspervector> User-agent: mu4e 1.4.13; emacs 27.1 From: Alexis To: supervision@list.skarnet.org Subject: Re: [request for review] Port of s6 documentation to mdoc(7) In-reply-to: Date: Tue, 01 Sep 2020 21:55:24 +1000 Message-ID: <873641yamr.fsf@ada> MIME-Version: 1.0 Content-Type: text/plain; format=flowed Laurent Bercot writes: > I'm totally willing to use a HTML schema we can negotiate, to > write > future documentation in. What I don't want to do is: > - Touch existing documentation, unless I have to rewrite the > content of > a page for some reason. Of course, if the conversion work is > done by > somebody else, I have no objection to upstreaming the new > documents. In terms of automating such a conversion, here are a few of the things the automation would need to do: * Determine whether some text is an environment variable. Environment variables in the current HTML aren't marked up. You might think that you could say "Well, if it's all caps it's an env var", but that won't work, because will catch things like SIGTERM and SO_REUSEADDR. You could special-case 'SIG*', but i'm not sure what could be done about things like SO_REUSEADDR. * Parse things like "s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i | -D uid:gid:gidlist ] account prog..." appropriately, so that mdoc/roff using Op, Fl and Ar can be produced. The parsing will also need keep track of the fact that further uses of "account" in the mdoc/roff might need to be preceded by an Fl macro. Of course, the word "account" is not necessarily referring to the "account" argument, but also to the notion of an account in general: in "s6-envuidgid looks account up by name in the account database", the first "account" should be preceded by Fl, but the second shouldn't. So this sort of thing would somehow need to be handled as well. Note that "-D uid:gid:gidlist" will require special handling, as that seems to also need use of Ns to produce the correct output, i.e. ".Op Fl i | D Ar uid Ns : Ns Ar gid Ns : Ns Ar gidlist". Although, `mandoc -T lint` currently produces a warning about the use of Ns there; if mdoc/roff experts have any suggestions as to The Correct Way to do this, i'm all ears. :-) * In accessrules.html, is used to indicate file paths, function types, variable types and the accessrules library itself; these cases will somehow need to be distinguished. (There are currently places in s6-accessrules.7 where, in my first pass, i've used Ql when i should actually be using Vt; that's one of the things i still need to fix.) So my guess is that trying to automate a conversion will be much more work than simply doing a conversion manually. Alexis.