From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id ce4d5b73 for ; Thu, 28 Mar 2019 12:20:00 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1h9Yh3-0006Jk-W6; Thu, 28 Mar 2019 18:19:59 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1h9Yh2-0003Pj-96; Thu, 28 Mar 2019 18:19:56 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1h9Yh2-0004Bi-5R; Thu, 28 Mar 2019 18:19:56 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 7e7a38a5; Thu, 28 Mar 2019 18:19:56 +0100 (CET) Date: Thu, 28 Mar 2019 18:19:56 +0100 From: Ingo Schwarze To: Stephen Gregoratto Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH docbook2mdoc] Add NODE_CONTRIB, NODE_PRODUCTNAME Message-ID: <20190328171956.GB48147@athene.usta.de> References: <20190327035224.7eyuctlnbt67pu5r@BlackBox> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190327035224.7eyuctlnbt67pu5r@BlackBox> User-Agent: Mutt/1.8.0 (2017-02-23) Hi Stephen, Stephen Gregoratto wrote on Wed, Mar 27, 2019 at 02:52:24PM +1100: > Here are some nodes I found in the wild. Thank you for the information about the two nodes. I wasn't aware of them yet and have added the information to my TODO list. Regarding the patch, you are no longer up to date. ;-) Unless you want to make at least one explicit formatting decision based on the presence of an element, adding it to "node.h" is no longer required. Elements can now be explicitly ignored, in the sense that they generate no node and that their content appears in their stead as children of their parent, with a line like { "productname", NODE_IGNORE }, in parse.c, elements[]. Yes, i know that "nohe.h" still contains enum constants for various nodes that are correctly not doing any formatting. I tend to remove those that are unlikely to ever require formatting, but i tend to keep those that are likely to require some handling when the program becomes better in the future. But for new nodes, i only add them when i start actually using them for formatting purposes. Regarding the additions to parse.c, even those are no longer needed. Elements with unknown names are now automatically ignored (in the above sense), except that they emit a warning with -W. So, a NODE_IGNORE line in parse.c as shown above is only needed to suppress the warning, which may be useful in two cases: (1) if it is unlikely that the element will ever need formatting (examples: , , ) or (2) if the element occurs so frequently that the warnings would be too noisy, making it hard to find warnings that actually matter (no examples currently). It seems to me neither applies here. > Technically is used to markup text as > copyright/trademark/registered, In that capacity, NODE_IGNORE is probably right, like for . > but the Systemd and GTK manuals use it to set the "source" argument > of TH in man(7). We have no need for it. So in that capacity, it would be NODE_DELETE. However, each element name can only have one enum constant attached to it. If requirements conflict depending on context, like in this case, one could make it NODE_PRODUCTNAME and then explicitly treat it as transparent in normal text (which needs no explicit code at all, nodes are transparent by default) and skip it in other contexts (which does need explicit code). But i'd prefer adding the NODE_PRODUCTNAME enum constant when the skipping code is implemented, not earlier: we are not really sure yet such skipping code will ever be needed, or are we? > is a bit odd case. It classifies an 's contributions > to the program/manual/code etc. Here's an example from GTK: > > > > Developer > Matthias > Clasen > > Right, handling properly is a challenge that is on my TODO list. There are three things to do that i'm aware of: (1) in normal text, stop skipping children like ; (2) below , , and the like, move the information down to the AUTHORS section (a slightly tricky task); (3) handle . Currently (and dto. with your patch), the above example is formatted as: .An Developer Matthias Clasen Instead, it should be: Developer: .An Matthias Clasen That's somewhat tricky (but still straightforward enough to implement with the recent improvements in the codebase) because NODE_AUTHOR has to print a NODE_CONTRIB child *before* calling macro_open("An"). It is sufficient to add the NODE_CONTRIB enum constant when that is implemented. > I'm setting it to be skipped for now, but if we ever start recording > s we could probably include this. Err, right now, elements *are* handled, and - with or without your patch - is *ignored* (in the sense explained above), not *skipped*; see and as examples of elements that are skipped (more formally, "deleted"). Yours, Ingo -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv