[{"id":1763976,"web_url":"http://patchwork.ozlabs.org/comment/1763976/","msgid":"","list_archive_url":null,"date":"2017-09-06T09:56:37","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":71764,"url":"http://patchwork.ozlabs.org/api/people/71764/","name":"Arturo Borrero Gonzalez","email":"arturo@netfilter.org"},"content":"On 6 September 2017 at 10:41, Phil Sutter wrote:\n> Beware: The conversion is incomplete and merely serves as base for\n> discussion.\n>\n> This patch converts nft.xml into asciidoc markup, top down until (and\n> including) stateful objects description. I stopped there because it's\n> the first chance of demonstrating my idea of splitting the documentation\n> into smaller pieces for convenience and maintainability.\n>\n> Regarding package dependencies, this \"just\" exchanges docbook with\n> asciidoc - dblatex is still required for PDF creation.\n>\n\nHi Phil,\n\nthanks for your initiative and hard work, it's really appreciated :-)\n\nRegarding the change, why asciidoc? why not markdown, or org-mode or\nreStructuredText?\nThere are many markup languages, it reminds me to xkcd #927 [0].\nI would prefer if we stick to groff, which seems to be the standard in Linux.\n\nRegarding the separation of text in different includes, why not\ncreating different manpages?\nNetfilter did this in the past with iptables(8) and iptables-extensions(8).\n\nBrainstorming:\n* nft(8) <-- main document, general info\n* nft-ct(8) <-- concrete info for ct objects\n* nft-counter(8) <-- concrete info for counter objets\n* nft-flowtables(8) <-- about flow tables\n* nft-quota(8) <--- concrete info for quotas\n* nft-performance(8) <--- concrete info about nftables sets, maps,\ndicts, concatenations, etc.\n* nft-ha(8) <--- for HA environments, loadbalancing etc\n\n[0] https://xkcd.com/927/\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnJsC2TVXz9sNc\n\tfor ;\n\tWed, 6 Sep 2017 19:57:03 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1752628AbdIFJ5C (ORCPT );\n\tWed, 6 Sep 2017 05:57:02 -0400","from mail-wm0-f53.google.com ([74.125.82.53]:37008 \"EHLO\n\tmail-wm0-f53.google.com\" rhost-flags-OK-OK-OK-OK) by vger.kernel.org\n\twith ESMTP id S1752351AbdIFJ5B (ORCPT\n\t);\n\tWed, 6 Sep 2017 05:57:01 -0400","by mail-wm0-f53.google.com with SMTP id u26so28964197wma.0\n\tfor ;\n\tWed, 06 Sep 2017 02:57:00 -0700 (PDT)","from mail-wm0-f46.google.com (mail-wm0-f46.google.com.\n\t[74.125.82.46]) by smtp.gmail.com with ESMTPSA id\n\tp14sm1210673edj.21.2017.09.06.02.56.58\n\tfor \n\t(version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);\n\tWed, 06 Sep 2017 02:56:58 -0700 (PDT)","by mail-wm0-f46.google.com with SMTP id i145so27502063wmf.1\n\tfor ;\n\tWed, 06 Sep 2017 02:56:58 -0700 (PDT)","by 10.80.167.166 with HTTP; Wed, 6 Sep 2017 02:56:37 -0700 (PDT)"],"X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:mime-version:in-reply-to:references:from:date\n\t:message-id:subject:to:cc;\n\tbh=8kV7R8d/4HIEduSY9epK8rHSczsLkTlmA04SboraTxs=;\n\tb=lo4bjP/mF6pYCRCEwbZfgEp9YEziGpW6gXns04XhYSoP8xUHELo0aOsCwYSB2lp34A\n\t2zm7gOLV+9JZFJBr4orri0EThzuoDyXmSrlDyYYIsS9gRGWf6J+fkHasgC9sQFcLttZD\n\tIYc4XbDPo/aC5IkLGKb1IxEtWMjt3004NLxDVkPhK+fFk8E87UKwu2iU6HFxkURJnDJy\n\tXuTLfIkiTe8CyFlCH2RGp17YyiMeO186csnExdSbx+QnLT1yfsVGmg9gApWeZY6cdiYv\n\tgvYUzlGRgc+WHqP57Tz71oQvzpWERaD+vraFStmpAmrD9sbZOLUAxT/x9A/BAVzL2tCp\n\t+zFw==","X-Gm-Message-State":"AHPjjUg7UOPulk+SijotGh9OCtmRRuqzLvO08ons3MHDqnnMqnpoGMMf\n\tesR3je1RdDnFr8JsEi0=","X-Received":["by 10.80.168.99 with SMTP id j90mr10001edc.10.1504691820038;\n\tWed, 06 Sep 2017 02:57:00 -0700 (PDT)","by 10.80.213.203 with SMTP id g11mr3405036edj.277.1504691818080; \n\tWed, 06 Sep 2017 02:56:58 -0700 (PDT)"],"X-Google-Smtp-Source":"ADKCNb4NKVnyoSjM8/kenh+r4SkuTcMCY160ax/z24m99QEOVm0LBuIMD4kiSymV1spXLCmoxQ5JI6iYjB4oHkxmxFo=","MIME-Version":"1.0","In-Reply-To":"<20170906084105.10915-1-phil@nwl.cc>","References":"<20170906084105.10915-1-phil@nwl.cc>","From":"Arturo Borrero Gonzalez ","Date":"Wed, 6 Sep 2017 11:56:37 +0200","X-Gmail-Original-Message-ID":"","Message-ID":"","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","To":"Phil Sutter ","Cc":"Pablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Content-Type":"text/plain; charset=\"UTF-8\"","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764035,"web_url":"http://patchwork.ozlabs.org/comment/1764035/","msgid":"<20170906113402.GA19026@salvia>","list_archive_url":null,"date":"2017-09-06T11:34:02","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":1315,"url":"http://patchwork.ozlabs.org/api/people/1315/","name":"Pablo Neira Ayuso","email":"pablo@netfilter.org"},"content":"Hi Arturo,\n\nOn Wed, Sep 06, 2017 at 11:56:37AM +0200, Arturo Borrero Gonzalez wrote:\n> On 6 September 2017 at 10:41, Phil Sutter wrote:\n> > Beware: The conversion is incomplete and merely serves as base for\n> > discussion.\n> >\n> > This patch converts nft.xml into asciidoc markup, top down until (and\n> > including) stateful objects description. I stopped there because it's\n> > the first chance of demonstrating my idea of splitting the documentation\n> > into smaller pieces for convenience and maintainability.\n> >\n> > Regarding package dependencies, this \"just\" exchanges docbook with\n> > asciidoc - dblatex is still required for PDF creation.\n> >\n> \n> Hi Phil,\n> \n> thanks for your initiative and hard work, it's really appreciated :-)\n> \n> Regarding the change, why asciidoc? why not markdown, or org-mode or\n> reStructuredText?\n> There are many markup languages, it reminds me to xkcd #927 [0].\n> I would prefer if we stick to groff, which seems to be the standard in Linux.\n\nNot willing to create a large thread debating what markup language\nchoice is better here, but I think asciidoc is a reasonable option.\n\n> Regarding the separation of text in different includes, why not\n> creating different manpages?\n> Netfilter did this in the past with iptables(8) and iptables-extensions(8).\n> \n> Brainstorming:\n> * nft(8) <-- main document, general info\n> * nft-ct(8) <-- concrete info for ct objects\n> * nft-counter(8) <-- concrete info for counter objets\n> * nft-flowtables(8) <-- about flow tables\n> * nft-quota(8) <--- concrete info for quotas\n> * nft-performance(8) <--- concrete info about nftables sets, maps,\n> dicts, concatenations, etc.\n> * nft-ha(8) <--- for HA environments, loadbalancing etc\n\nSplitting manpage is a sensible option if we consider it's getting too\nlarge, we can do this in incremental steps after the conversion.\n\nCheers.\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnM1d50nGz9s9Y\n\tfor ;\n\tWed, 6 Sep 2017 21:34:29 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1752666AbdIFLe2 (ORCPT );\n\tWed, 6 Sep 2017 07:34:28 -0400","from ganesha.gnumonks.org ([213.95.27.120]:37288 \"EHLO\n\tganesha.gnumonks.org\" rhost-flags-OK-OK-OK-OK) by vger.kernel.org\n\twith ESMTP id S1752409AbdIFLe2 (ORCPT\n\t);\n\tWed, 6 Sep 2017 07:34:28 -0400","from 129.166.216.87.static.jazztel.es ([87.216.166.129]\n\thelo=gnumonks.org) by ganesha.gnumonks.org with esmtpsa\n\t(TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2)\n\t(envelope-from )\n\tid 1dpYaq-0006Tx-Qu; Wed, 06 Sep 2017 13:34:06 +0200"],"Date":"Wed, 6 Sep 2017 13:34:02 +0200","From":"Pablo Neira Ayuso ","To":"Arturo Borrero Gonzalez ","Cc":"Phil Sutter , Netfilter Development Mailing list \n\t","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","Message-ID":"<20170906113402.GA19026@salvia>","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=us-ascii","Content-Disposition":"inline","In-Reply-To":"","User-Agent":"Mutt/1.5.23 (2014-03-12)","X-Spam-Score":"-2.7 (--)","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764051,"web_url":"http://patchwork.ozlabs.org/comment/1764051/","msgid":"","list_archive_url":null,"date":"2017-09-06T11:53:19","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":13886,"url":"http://patchwork.ozlabs.org/api/people/13886/","name":"Jan Engelhardt","email":"jengelh@inai.de"},"content":"On Wednesday 2017-09-06 11:56, Arturo Borrero Gonzalez wrote:\n>\n>Regarding the separation of text in different includes, why not creating\n>different manpages? Netfilter did this in the past with iptables(8) and\n>iptables-extensions(8).\n\nThe split into iptables-extensions.8 happened not because of size or topic, but\nbecause iptables.8 and ip6tables.8 had redundant copies of numerous sections of\neach other, and they sometimes were quite small sections too (for this reason,\nit only has 9 manuals in total, not 96).\n\n>Brainstorming:\n>* nft-performance(8) <--- concrete info about nftables sets, maps,\n>dicts, concatenations, etc.\n\nthose seem more like \"datatypes\" than \"performance\".\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnMRS1YHpz9sBW\n\tfor ;\n\tWed, 6 Sep 2017 21:53:24 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1753492AbdIFLxX (ORCPT );\n\tWed, 6 Sep 2017 07:53:23 -0400","from a3.inai.de ([88.198.180.161]:57366 \"EHLO a3.inai.de\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S1753268AbdIFLxU (ORCPT );\n\tWed, 6 Sep 2017 07:53:20 -0400","by a3.inai.de (Postfix, from userid 25121)\n\tid 5ED2B195F668A; Wed, 6 Sep 2017 13:53:19 +0200 (CEST)","from localhost (localhost [127.0.0.1])\n\tby a3.inai.de (Postfix) with ESMTP id 5C2FA17AAF0A;\n\tWed, 6 Sep 2017 13:53:19 +0200 (CEST)"],"Date":"Wed, 6 Sep 2017 13:53:19 +0200 (CEST)","From":"Jan Engelhardt ","To":"Arturo Borrero Gonzalez ","cc":"Phil Sutter , Pablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","In-Reply-To":"","Message-ID":"","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t","User-Agent":"Alpine 2.21 (LSU 202 2017-01-01)","MIME-Version":"1.0","Content-Type":"text/plain; charset=US-ASCII","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764052,"web_url":"http://patchwork.ozlabs.org/comment/1764052/","msgid":"<20170906115856.GC2399@orbyte.nwl.cc>","list_archive_url":null,"date":"2017-09-06T11:58:56","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":4285,"url":"http://patchwork.ozlabs.org/api/people/4285/","name":"Phil Sutter","email":"phil@nwl.cc"},"content":"Hi Arturo,\n\nOn Wed, Sep 06, 2017 at 11:56:37AM +0200, Arturo Borrero Gonzalez wrote:\n> On 6 September 2017 at 10:41, Phil Sutter wrote:\n> > Beware: The conversion is incomplete and merely serves as base for\n> > discussion.\n> >\n> > This patch converts nft.xml into asciidoc markup, top down until (and\n> > including) stateful objects description. I stopped there because it's\n> > the first chance of demonstrating my idea of splitting the documentation\n> > into smaller pieces for convenience and maintainability.\n> >\n> > Regarding package dependencies, this \"just\" exchanges docbook with\n> > asciidoc - dblatex is still required for PDF creation.\n> >\n> \n> Hi Phil,\n> \n> thanks for your initiative and hard work, it's really appreciated :-)\n\nThanks!\n\n> Regarding the change, why asciidoc? why not markdown, or org-mode or\n> reStructuredText?\n\nWell, asciidoc is basicaly markdown on steroids, I fear we'll soon miss\nfeatures if we stuck to plain markdown. Also see this URL for a\ncomparison: [1].\n\nI tend to ignore org-mode because I'm not an emacs user, and I guess\nabout 50% of (potential) nftables contributors feel the same about that.\n:)\n\nRegarding reStructuredText, did you look at how tables are written\nthere? If not, see here[2]. I really think that speaks for itself.\n\n> There are many markup languages, it reminds me to xkcd #927 [0].\n\nWell, the difference here is that I'm not inventing anything new but\nsearch for better options amongst the existing solutions. :P\n\n> I would prefer if we stick to groff, which seems to be the standard in Linux.\n\nYes, this is the very basic alternative but as said I think providing\nusers with an easier to use markup makes sense.\n\n> Regarding the separation of text in different includes, why not\n> creating different manpages?\n> Netfilter did this in the past with iptables(8) and iptables-extensions(8).\n> \n> Brainstorming:\n> * nft(8) <-- main document, general info\n> * nft-ct(8) <-- concrete info for ct objects\n> * nft-counter(8) <-- concrete info for counter objets\n> * nft-flowtables(8) <-- about flow tables\n> * nft-quota(8) <--- concrete info for quotas\n> * nft-performance(8) <--- concrete info about nftables sets, maps,\n> dicts, concatenations, etc.\n> * nft-ha(8) <--- for HA environments, loadbalancing etc\n\nWell, I don't think nft.8's current size requires to split it into\nsmaller files at this point.\n\nCheers, Phil\n\n[1] https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/asciidoc-vs-markdown.adoc\n[2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnMYv4JPLz9s8J\n\tfor ;\n\tWed, 6 Sep 2017 21:58:59 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1753060AbdIFL66 (ORCPT );\n\tWed, 6 Sep 2017 07:58:58 -0400","from orbyte.nwl.cc ([151.80.46.58]:60002 \"EHLO orbyte.nwl.cc\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S1752666AbdIFL66 (ORCPT );\n\tWed, 6 Sep 2017 07:58:58 -0400","from n0-1 by orbyte.nwl.cc with local (Exim 4.89)\n\t(envelope-from )\n\tid 1dpYyu-0002wu-It; Wed, 06 Sep 2017 13:58:56 +0200"],"Date":"Wed, 6 Sep 2017 13:58:56 +0200","From":"Phil Sutter ","To":"Arturo Borrero Gonzalez ","Cc":"Pablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","Message-ID":"<20170906115856.GC2399@orbyte.nwl.cc>","Mail-Followup-To":"Phil Sutter ,\n\tArturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=us-ascii","Content-Disposition":"inline","In-Reply-To":"","User-Agent":"Mutt/1.7.2 (2016-11-26)","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764102,"web_url":"http://patchwork.ozlabs.org/comment/1764102/","msgid":"","list_archive_url":null,"date":"2017-09-06T13:25:51","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":13886,"url":"http://patchwork.ozlabs.org/api/people/13886/","name":"Jan Engelhardt","email":"jengelh@inai.de"},"content":"On Wednesday 2017-09-06 13:58, Phil Sutter wrote:\n>\n>Regarding reStructuredText, did you look at how tables are written\n>there? If not, see here[2]. I really think that speaks for itself.\n\nMarkup is the least problem. Tables, when rendered, have a tendency to quickly\ngrow too large for the display container because there is just so much data to\nshow.\n\nKnowing that, people just avoid them most of the time for groff - and if I may\nsay so, it has not reduced the document quality.\n\n\n>> There are many markup languages, it reminds me to xkcd #927 [0].\n>\n>Well, the difference here is that I'm not inventing anything new but\n>search for better options amongst the existing solutions. :P\n\nThat would be to stay with docbook then, because RST/MD/A2 do not seem to have\nleft themselves a lot of room for later extension.\n\n\n>> I would prefer if we stick to groff, which seems to be the standard in Linux.\n>\n>Yes, this is the very basic alternative but as said I think providing\n>users with an easier to use markup makes sense.\n\nUsers read the rendered text, not the markup.\n\nAll of the glorious old markups are \"unreadable\" enough to be fed through a\nprogram to give a visually-cooked, markup-free rendering (browser,\n/usr/bin/man, evince, etc.) MediaWiki, RST, MD and asciidoc on the other hand\nhowever seem to propagate the use of just cat/less with very short markup,\nwhich, to a user, is not too bad to look at, but also not too visually pleasing\neither, giving the worst of both worlds :-p\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnPVH3pf2z9sNV\n\tfor ;\n\tWed, 6 Sep 2017 23:25:59 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1754395AbdIFNZz (ORCPT );\n\tWed, 6 Sep 2017 09:25:55 -0400","from a3.inai.de ([88.198.180.161]:35916 \"EHLO a3.inai.de\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S1753775AbdIFNZw (ORCPT );\n\tWed, 6 Sep 2017 09:25:52 -0400","by a3.inai.de (Postfix, from userid 25121)\n\tid 2D3E3195F668A; Wed, 6 Sep 2017 15:25:51 +0200 (CEST)","from localhost (localhost [127.0.0.1])\n\tby a3.inai.de (Postfix) with ESMTP id 2891A17AAF0A;\n\tWed, 6 Sep 2017 15:25:51 +0200 (CEST)"],"Date":"Wed, 6 Sep 2017 15:25:51 +0200 (CEST)","From":"Jan Engelhardt ","To":"Phil Sutter ","cc":"Arturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","In-Reply-To":"<20170906115856.GC2399@orbyte.nwl.cc>","Message-ID":"","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t\n\t<20170906115856.GC2399@orbyte.nwl.cc>","User-Agent":"Alpine 2.21 (LSU 202 2017-01-01)","MIME-Version":"1.0","Content-Type":"text/plain; charset=US-ASCII","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764131,"web_url":"http://patchwork.ozlabs.org/comment/1764131/","msgid":"<20170906140233.GD2399@orbyte.nwl.cc>","list_archive_url":null,"date":"2017-09-06T14:02:33","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":4285,"url":"http://patchwork.ozlabs.org/api/people/4285/","name":"Phil Sutter","email":"phil@nwl.cc"},"content":"Hi,\n\nOn Wed, Sep 06, 2017 at 03:25:51PM +0200, Jan Engelhardt wrote:\n> On Wednesday 2017-09-06 13:58, Phil Sutter wrote:\n> >\n> >Regarding reStructuredText, did you look at how tables are written\n> >there? If not, see here[2]. I really think that speaks for itself.\n> \n> Markup is the least problem. Tables, when rendered, have a tendency to quickly\n> grow too large for the display container because there is just so much data to\n> show.\n\nIt really matters if the markup specs suggest to draw ASCII art\npictures. The real problem though is that reStructuredText is meant to\nbe read as is and that is not required nor wanted in our case since we\ngenerate a man page anyway.\n\n> Knowing that, people just avoid them most of the time for groff - and if I may\n> say so, it has not reduced the document quality.\n\nRight now, nft.8 makes extensive use of tables which is why I considered\nproper table support an important feature. OTOH I didn't experience\nrendering issues with them in nft.8, did you?\n\n> >> There are many markup languages, it reminds me to xkcd #927 [0].\n> >\n> >Well, the difference here is that I'm not inventing anything new but\n> >search for better options amongst the existing solutions. :P\n> \n> That would be to stay with docbook then, because RST/MD/A2 do not seem to have\n> left themselves a lot of room for later extension.\n\nWhat extensions do you have in mind?\n\n> >> I would prefer if we stick to groff, which seems to be the standard in Linux.\n> >\n> >Yes, this is the very basic alternative but as said I think providing\n> >users with an easier to use markup makes sense.\n> \n> Users read the rendered text, not the markup.\n\nYes, you are right of course. I mixed up users with contributors again.\n\n> All of the glorious old markups are \"unreadable\" enough to be fed through a\n> program to give a visually-cooked, markup-free rendering (browser,\n> /usr/bin/man, evince, etc.) MediaWiki, RST, MD and asciidoc on the other hand\n> however seem to propagate the use of just cat/less with very short markup,\n> which, to a user, is not too bad to look at, but also not too visually pleasing\n> either, giving the worst of both worlds :-p\n\nNow you seem to mix up users and contributors: I never suggested to\nprovide documentation to users in a different format than roff (rendered\nby 'man'), but to provide people editing the documentation with\nsomething more intuitive than docbook or roff.\n\nCheers, Phil\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnQJc2Wdtz9s9Y\n\tfor ;\n\tThu, 7 Sep 2017 00:02:40 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S932410AbdIFOCh (ORCPT );\n\tWed, 6 Sep 2017 10:02:37 -0400","from orbyte.nwl.cc ([151.80.46.58]:60244 \"EHLO orbyte.nwl.cc\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S932308AbdIFOCg (ORCPT ); \n\tWed, 6 Sep 2017 10:02:36 -0400","from n0-1 by orbyte.nwl.cc with local (Exim 4.89)\n\t(envelope-from )\n\tid 1dpauX-0004FC-OS; Wed, 06 Sep 2017 16:02:33 +0200"],"Date":"Wed, 6 Sep 2017 16:02:33 +0200","From":"Phil Sutter ","To":"Jan Engelhardt ","Cc":"Arturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","Message-ID":"<20170906140233.GD2399@orbyte.nwl.cc>","Mail-Followup-To":"Phil Sutter ,\n\tJan Engelhardt ,\n\tArturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t\n\t<20170906115856.GC2399@orbyte.nwl.cc>\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=us-ascii","Content-Disposition":"inline","In-Reply-To":"","User-Agent":"Mutt/1.7.2 (2016-11-26)","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1764149,"web_url":"http://patchwork.ozlabs.org/comment/1764149/","msgid":"","list_archive_url":null,"date":"2017-09-06T14:29:00","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":13886,"url":"http://patchwork.ozlabs.org/api/people/13886/","name":"Jan Engelhardt","email":"jengelh@inai.de"},"content":"On Wednesday 2017-09-06 16:02, Phil Sutter wrote:\n>> Knowing that, people just avoid them most of the time for groff - and if I may\n>> say so, it has not reduced the document quality.\n>\n>Right now, nft.8 makes extensive use of tables which is why I considered\n>proper table support an important feature. OTOH I didn't experience\n>rendering issues with them in nft.8, did you?\n\nI do. For some reason, the right margin of the table is 60% of the\nterminal width. (width 120 => table up to col #63, terminal 80 cols\n=> table up to col #50).\n\n ┌────────────┬─────────────────────────────────────────┐\n │Hook │ Description │\n ├────────────┼─────────────────────────────────────────┤\n │prerouting │ All packets entering the system are │\n │ │ processed by the prerouting hook. It is │\n │ │ invoked before the routing process and │\n │ │ is used for early filtering or changing │\n │ │ packet attributes that affect routing. │\n ├────────────┼─────────────────────────────────────────┤\n │input │ Packets delivered to the local system │\n │ │ are processed by the input hook. │\n ├────────────┼─────────────────────────────────────────┤\n │forward │ Packets forwarded to a different host │\n │ │ are processed by the forward hook. │\n ├────────────┼─────────────────────────────────────────┤\n │output │ Packets sent by local processes are │\n │ │ processed by the output hook. │\n ├────────────┼─────────────────────────────────────────┤\n │postrouting │ All packets leaving the system are pro- │\n │ │ cessed by the postrouting hook. │\n └────────────┴─────────────────────────────────────────┘\n\nHowever, what I tried to express is the problem with tables is that\none column has almost no text and another has a lot of it, like this\none. This causes large amounts of whitespace in column 1 in this\ncase. Personally, I would have placed the hooks and their\nexplanations as (the equivalent of)\n\n.TP\n\\fBprerouting\\fP\nAll packets enter ...\n.TP\n\\fBinput\\fP\nPackets delivered ...\n\nOr if the source material was HTML, perhaps just\n\n
    \n
  • prerouting: All packets enter...
    • \n
  • input: Packets delivered...
    • \n
\n\n\nThe rectangular grid is overkill, because you are not trying to do\na figurative police lineup (leave tables for e.g.\nhttps://en.wikipedia.org/wiki/Comparison_of_Linux_distributions#Instruction_set_architecture_support\n)\n\n\nIn another way, I could also ask why hooks are in tables, and commands \n(\"add\", \"flush\", etc.) are in TP-style. What makes hooks so special that \nthey deserve a table, despite their keyword being the same short length \nas the commands.\n\n\n\n>> >> There are many markup languages, it reminds me to xkcd #927 [0].\n>> >\n>> >Well, the difference here is that I'm not inventing anything new but\n>> >search for better options amongst the existing solutions. :P\n>> \n>> That would be to stay with docbook then, because RST/MD/A2 do not seem to have\n>> left themselves a lot of room for later extension.\n>\n>What extensions do you have in mind?\n\nI kind of left that open; it seemed you implied there is something\n(the \"better option\") that MD couldn't do that asciidoc could. That\nthing, docbook should already have.\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xnQv34S9cz9t50\n\tfor ;\n\tThu, 7 Sep 2017 00:29:03 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S932463AbdIFO3C (ORCPT );\n\tWed, 6 Sep 2017 10:29:02 -0400","from a3.inai.de ([88.198.180.161]:40702 \"EHLO a3.inai.de\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S932260AbdIFO3C (ORCPT ); \n\tWed, 6 Sep 2017 10:29:02 -0400","by a3.inai.de (Postfix, from userid 25121)\n\tid B286D195F668A; Wed, 6 Sep 2017 16:29:00 +0200 (CEST)","from localhost (localhost [127.0.0.1])\n\tby a3.inai.de (Postfix) with ESMTP id B19A317AAF0A;\n\tWed, 6 Sep 2017 16:29:00 +0200 (CEST)"],"Date":"Wed, 6 Sep 2017 16:29:00 +0200 (CEST)","From":"Jan Engelhardt ","To":"Phil Sutter ","cc":"Arturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","In-Reply-To":"<20170906140233.GD2399@orbyte.nwl.cc>","Message-ID":"","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t\n\t<20170906115856.GC2399@orbyte.nwl.cc>\n\t\n\t<20170906140233.GD2399@orbyte.nwl.cc>","User-Agent":"Alpine 2.21 (LSU 202 2017-01-01)","MIME-Version":"1.0","Content-Type":"text/plain; charset=UTF-8","Content-Transfer-Encoding":"8BIT","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}},{"id":1765161,"web_url":"http://patchwork.ozlabs.org/comment/1765161/","msgid":"<20170908085321.GJ2399@orbyte.nwl.cc>","list_archive_url":null,"date":"2017-09-08T08:53:21","subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","submitter":{"id":4285,"url":"http://patchwork.ozlabs.org/api/people/4285/","name":"Phil Sutter","email":"phil@nwl.cc"},"content":"On Wed, Sep 06, 2017 at 04:29:00PM +0200, Jan Engelhardt wrote:\n> \n> On Wednesday 2017-09-06 16:02, Phil Sutter wrote:\n> >> Knowing that, people just avoid them most of the time for groff - and if I may\n> >> say so, it has not reduced the document quality.\n> >\n> >Right now, nft.8 makes extensive use of tables which is why I considered\n> >proper table support an important feature. OTOH I didn't experience\n> >rendering issues with them in nft.8, did you?\n> \n> I do. For some reason, the right margin of the table is 60% of the\n> terminal width. (width 120 => table up to col #63, terminal 80 cols\n> => table up to col #50).\n\nOh, I see that too, also in my asciidoc PoC. Explicitly setting the\ntable width to 100% doesn't help either. Maybe this is a problem in\ngroff? The tables span the whole page in asciidoc's PDF output at least.\n\n[...]\n> However, what I tried to express is the problem with tables is that\n> one column has almost no text and another has a lot of it, like this\n> one. This causes large amounts of whitespace in column 1 in this\n> case. Personally, I would have placed the hooks and their\n> explanations as (the equivalent of)\n> \n> .TP\n> \\fBprerouting\\fP\n> All packets enter ...\n> .TP\n> \\fBinput\\fP\n> Packets delivered ...\n> \n> Or if the source material was HTML, perhaps just\n> \n>
    \n>
  • prerouting: All packets enter...
    • \n>
  • input: Packets delivered...
    • \n>
\n\nYes, we should indeed convert two-column tables to these labeled lists\nif they are merely keyword descriptions. I'm not sure about other cases,\nsometimes having the table headings allows to provide information in a\nmore compact form than embedding everything into a paragraph of text.\n\n[...]\n> In another way, I could also ask why hooks are in tables, and commands \n> (\"add\", \"flush\", etc.) are in TP-style. What makes hooks so special that \n> they deserve a table, despite their keyword being the same short length \n> as the commands.\n\nMany of the tables seem to be there for reasons of document structure,\ne.g. those below DATA TYPES. I don't think that is a bad thing per se.\n\n> >> >> There are many markup languages, it reminds me to xkcd #927 [0].\n> >> >\n> >> >Well, the difference here is that I'm not inventing anything new but\n> >> >search for better options amongst the existing solutions. :P\n> >> \n> >> That would be to stay with docbook then, because RST/MD/A2 do not seem to have\n> >> left themselves a lot of room for later extension.\n> >\n> >What extensions do you have in mind?\n> \n> I kind of left that open; it seemed you implied there is something\n> (the \"better option\") that MD couldn't do that asciidoc could. That\n> thing, docbook should already have.\n\nI think docbook is the most \"feature complete\" solution amongst those\nmentioned. My personal motivation to replace it is basically founded by\ntwo things:\n\n1) XML is not quite editor-friendly. I found myself spending way more\n time opening and closing tags than I had anticipated for whenever I\n worked on content.\n\n2) I didn't like how docbook formats synopfragment/synopfragmentref\n constructs. Maybe this could be changed by using some customization\n though. Also I didn't see an equivalent to it in asciidoc - BNF-style\n referencing is done manually there.\n\nCheers, Phil\n--\nTo unsubscribe from this list: send the line \"unsubscribe netfilter-devel\" in\nthe body of a message to majordomo@vger.kernel.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=netfilter-devel-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xpWLw52Q5z9sBW\n\tfor ;\n\tFri, 8 Sep 2017 18:53:28 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1755793AbdIHIx1 (ORCPT );\n\tFri, 8 Sep 2017 04:53:27 -0400","from orbyte.nwl.cc ([151.80.46.58]:36662 \"EHLO orbyte.nwl.cc\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S1754751AbdIHIxY (ORCPT );\n\tFri, 8 Sep 2017 04:53:24 -0400","from n0-1 by orbyte.nwl.cc with local (Exim 4.89)\n\t(envelope-from )\n\tid 1dqF2P-0006rX-7Y; Fri, 08 Sep 2017 10:53:21 +0200"],"Date":"Fri, 8 Sep 2017 10:53:21 +0200","From":"Phil Sutter ","To":"Jan Engelhardt ","Cc":"Arturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","Subject":"Re: [nft PATCH RFC] Convert man page source to asciidoc","Message-ID":"<20170908085321.GJ2399@orbyte.nwl.cc>","Mail-Followup-To":"Phil Sutter ,\n\tJan Engelhardt ,\n\tArturo Borrero Gonzalez ,\n\tPablo Neira Ayuso ,\n\tNetfilter Development Mailing list ","References":"<20170906084105.10915-1-phil@nwl.cc>\n\t\n\t<20170906115856.GC2399@orbyte.nwl.cc>\n\t\n\t<20170906140233.GD2399@orbyte.nwl.cc>\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=us-ascii","Content-Disposition":"inline","In-Reply-To":"","User-Agent":"Mutt/1.7.2 (2016-11-26)","Sender":"netfilter-devel-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"netfilter-devel@vger.kernel.org"}}]