From patchwork Fri Jun 18 20:30:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Felipe Contreras X-Patchwork-Id: 12332147 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6AACAC49361 for ; Fri, 18 Jun 2021 20:31:08 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 513CA61284 for ; Fri, 18 Jun 2021 20:31:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233639AbhFRUdQ (ORCPT ); Fri, 18 Jun 2021 16:33:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42572 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230430AbhFRUdO (ORCPT ); Fri, 18 Jun 2021 16:33:14 -0400 Received: from mail-oi1-x232.google.com (mail-oi1-x232.google.com [IPv6:2607:f8b0:4864:20::232]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 653C3C061574 for ; Fri, 18 Jun 2021 13:31:03 -0700 (PDT) Received: by mail-oi1-x232.google.com with SMTP id m137so11887239oig.6 for ; Fri, 18 Jun 2021 13:31:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=dhzsJpzf2MVeOFaXgmv0bV0xP862X5eYHOBB1JjtAOg=; b=uVEuDVyi7X10TYxvSV+BtVAAMDjN9ssnjDzRIWvCyFX70/ohbS2CxCe02zCSm/i6O5 cUYfmGWgk2oz9j3QItUYGdnoWWyfsq9To7+nUTqTPHbRisivsICXVhK2PzpPNyGXNXdO ewkHWQPDyeyjpoPOv+zSHL7AU8yfnlYXOi+c7K/jSOzG9I6t9ufwnRehpDZLU1zibuQ2 o5lPsDji5e6gnqd/cvY/tLdRhYI+rOrYmGiMCsyLGNJPX9cKSMugrA558/lwJLTEe9zw oygkq/ljjnkwt39A/W/HreW/2417I/gIMmRa9Q09zgo9geaF6fLcWs+YBtq9Qrnln++z qsUg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=dhzsJpzf2MVeOFaXgmv0bV0xP862X5eYHOBB1JjtAOg=; b=LBr8mgUMtV2O89DR5O/Zbt4qL2lhL1PaH/oq7Z+38FDIBk884pDqJNhJ9dkiODnfi2 de7lOWqeEydErmRQjB5TX4vIznK3cIBo69AvD+phDGvmjFC7d9hM89Ab9E67VGNvYyRf MPGmKavEfdejoFpMLkgHQ7s/ds+nZDkfaVzRAH2Cj92je8fFZs5cdgLQiAwQW8EHaysc 4ZGEEBYs0o2h0OvqdR2qluy6e5LlEnl8rjH3behrr4eSo1pB39pPYiUAESo857R/LSIt sQCqZfvH5aZKNLmAkXz5cQaEqZNrfHnWuZLmbGQctjCOcru+nsYGbJFFBSbhbTKO2C8Z uowA== X-Gm-Message-State: AOAM530BExAoKMcUhM91UQP7fkymQt6CGshbkiEwPJQ8iEhGQphNlWL3 Dt/tQwu+73ZBAGqijHj6qIn2U0wRGcdDpg== X-Google-Smtp-Source: ABdhPJzjDgP4RylV84d1Yk8n5qtSQcYtBFAJqFgM/2+E2i+7SDJNsJ0mRtZjq2mDht/rY9dPh3sYLg== X-Received: by 2002:aca:dac5:: with SMTP id r188mr16251402oig.100.1624048261116; Fri, 18 Jun 2021 13:31:01 -0700 (PDT) Received: from localhost (fixed-187-188-155-231.totalplay.net. [187.188.155.231]) by smtp.gmail.com with ESMTPSA id e19sm2021298oiw.24.2021.06.18.13.31.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Jun 2021 13:31:00 -0700 (PDT) From: Felipe Contreras To: git@vger.kernel.org Cc: "brian m . carlson" , =?utf-8?q?Martin_?= =?utf-8?q?=C3=85gren?= , Bagas Sanjaya , Jeff King , Junio C Hamano , Felipe Contreras Subject: [RFC/NOPATCHv3 1/4] doc: add an option to have Asciidoctor build man pages directly Date: Fri, 18 Jun 2021 15:30:54 -0500 Message-Id: <20210618203057.790320-2-felipe.contreras@gmail.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210618203057.790320-1-felipe.contreras@gmail.com> References: <20210618203057.790320-1-felipe.contreras@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: "brian m. carlson" Asciidoctor contains a converter to generate man pages. In some environments, where building only the manual pages and not the other documentation is desired, installing a toolchain for building DocBook-based manual pages may be burdensome, and using Asciidoctor directly may be easier, so let's add an option to build manual pages using Asciidoctor without the DocBook toolchain. We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't contain proper handling of the apostrophe, which is controlled normally by the GNU_ROFF option. This option for the DocBook toolchain, as well as newer versions of Asciidoctor, makes groff output an ASCII apostrophe instead of a Unicode apostrophe in text, so as to make copy and pasting commands easier. These newer versions of Asciidoctor (1.5.3 and above) detect groff and do the right thing in all cases, so the GNU_ROFF option is obsolete in this case. Because Asciidoctor versions before 2.0 had a few problems with man page output, let's default this to off for now, since some common distros are still on 1.5. If users are using a more modern toolchain or don't care about the rendering issues, they can enable the option. Suggested-by: Bagas Sanjaya Original-patch-by: Felipe Contreras Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 12 +++++++++++- Makefile | 4 ++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 81d1bf7a04..d3103c3dde 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -187,6 +187,9 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation XMLTO_EXTRA += -x manpage.xsl +ifdef USE_ASCIIDOCTOR_MANPAGE +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage +endif endif SHELL_PATH ?= $(SHELL) @@ -325,7 +328,7 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ date >$@ -TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE)) GIT-ASCIIDOCFLAGS: FORCE @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ @@ -358,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ +ifdef TXT_TO_MAN +%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_MAN) -o $@+ $< && \ + mv $@+ $@ +else %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< +endif %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ diff --git a/Makefile b/Makefile index f3dc217832..48547e2c3b 100644 --- a/Makefile +++ b/Makefile @@ -285,6 +285,10 @@ all:: # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the # documentation. # +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend +# instead of building manual pages from DocBook (using xmlto). Has no effect +# unless USE_ASCIIDOCTOR is set. +# # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor # Extensions Lab if you have it available. # From patchwork Fri Jun 18 20:30:55 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Felipe Contreras X-Patchwork-Id: 12332145 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9077EC48BE8 for ; Fri, 18 Jun 2021 20:31:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 718FD6124C for ; Fri, 18 Jun 2021 20:31:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233558AbhFRUdP (ORCPT ); Fri, 18 Jun 2021 16:33:15 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42574 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232851AbhFRUdO (ORCPT ); Fri, 18 Jun 2021 16:33:14 -0400 Received: from mail-ot1-x32f.google.com (mail-ot1-x32f.google.com [IPv6:2607:f8b0:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8CA67C06175F for ; Fri, 18 Jun 2021 13:31:03 -0700 (PDT) Received: by mail-ot1-x32f.google.com with SMTP id i12-20020a05683033ecb02903346fa0f74dso10912899otu.10 for ; Fri, 18 Jun 2021 13:31:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Na2Pfgw7GEo8towg7xd9U4gTnvSsL575TGx4e6jDyYc=; b=kZD5hF6spXfYfDQjg/Jby79wQD6xOqy/hq+4Hz7o11w8PXFC4csuQYLbNU/ilWluwL v54T2rT3dnh656dAngYZMzowBCDUXh97PW2HaLej93pPyd1ejPC29SLrwk/GT1nAcbri YJkHRArO59HdVIyeN3EspmGdjSZdtpcY4KnmIzYu/qYb+ARWh8qx3Qf5jD+CJseh1YRT s7dYQ4Qalk3q5FMXLAvazlx2qaTswJDGkjVIFDhNbTlliKA0GU31fpFCzyiZsF7Be9Up LciyFSpgRYdQ8HwEGvSrYGC4QhESnaGJx9f0xBGdKWNF4nl1FgdcDw6Cdrl/3OvkizGL lXSg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Na2Pfgw7GEo8towg7xd9U4gTnvSsL575TGx4e6jDyYc=; b=UenyBIUKW8eEaZLwvqtDQ23luzzxyipOFKTAmmd/txYGDl105Ie/FeDxUE5u9wHNQv PWwNY+oZw2n23YOS9HvqPJnav//dbZVw2u2gseDZJ3Ykgu19FT6lZdDk32NlrNZlmEZ2 tFvUqG4iqbMBYSxFrlJEq1O19S+BkCcbGyEvYBjp8drIkQzbJpuPjAqwhdXnhdWFEHg1 ObzFe9y2teExV5bfKpl0ePdnVK4g9gFfKpPV5IxMG0a5OftF2Te5J1ctGs88/BquAs1b D77f6GCVm6j1ysoDfiZnaHHgcpRmIdBCv04u4b6RX8BxdpdldB5K9YmAluuql6u0MiIz TvJA== X-Gm-Message-State: AOAM5338H71dGHkG3RSIiNynu84Hlsd8ROsticaHkb10ClkF9ssLti6O M99OERlvl0iJbC3FgK+lkonJL42PNzlk5w== X-Google-Smtp-Source: ABdhPJyIptcsMOkbQsJWz7W6sXF7SxqQOXa4PsxvQknGMMRkKsbzNWJUWe4W7AkzzlQoEomY9USJeA== X-Received: by 2002:a9d:aa5:: with SMTP id 34mr8190756otq.183.1624048262646; Fri, 18 Jun 2021 13:31:02 -0700 (PDT) Received: from localhost (fixed-187-188-155-231.totalplay.net. [187.188.155.231]) by smtp.gmail.com with ESMTPSA id h2sm2041688oog.16.2021.06.18.13.31.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Jun 2021 13:31:02 -0700 (PDT) From: Felipe Contreras To: git@vger.kernel.org Cc: "brian m . carlson" , =?utf-8?q?Martin_?= =?utf-8?q?=C3=85gren?= , Bagas Sanjaya , Jeff King , Junio C Hamano Subject: [RFC/NOPATCHv3 2/4] doc: add linkgit macros for asciidoctor Date: Fri, 18 Jun 2021 15:30:55 -0500 Message-Id: <20210618203057.790320-3-felipe.contreras@gmail.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210618203057.790320-1-felipe.contreras@gmail.com> References: <20210618203057.790320-1-felipe.contreras@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: "brian m. carlson" We also need to update the code that tells Asciidoctor how to format our linkgit macros so that it can output proper code for man pages. Be careful to reset the font to the previous after the change. In order to do so, we must reset to the previous after each font change so the previous state at the end is the state before our inserted text, since troff only remembers one previous font. We insert \e before each font-change backslash so Asciidoctor doesn't convert them into \*(rs, the reverse solidus character, and instead leaves them as we wanted them. Signed-off-by: brian m. carlson --- Documentation/asciidoctor-extensions.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index d906a00803..620b3d7a88 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -15,6 +15,8 @@ module Git "#{target}(#{attrs[1]})" elsif parent.document.basebackend? 'html' %(#{target}(#{attrs[1]})) + elsif parent.document.basebackend? 'manpage' + %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP) elsif parent.document.basebackend? 'docbook' "\n" \ "#{target}" \ From patchwork Fri Jun 18 20:30:56 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Felipe Contreras X-Patchwork-Id: 12332149 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 39C07C48BDF for ; Fri, 18 Jun 2021 20:31:09 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1CCD961284 for ; Fri, 18 Jun 2021 20:31:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232851AbhFRUdR (ORCPT ); Fri, 18 Jun 2021 16:33:17 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42582 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232943AbhFRUdO (ORCPT ); Fri, 18 Jun 2021 16:33:14 -0400 Received: from mail-ot1-x32d.google.com (mail-ot1-x32d.google.com [IPv6:2607:f8b0:4864:20::32d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1BD1CC061574 for ; Fri, 18 Jun 2021 13:31:05 -0700 (PDT) Received: by mail-ot1-x32d.google.com with SMTP id h24-20020a9d64180000b029036edcf8f9a6so10946936otl.3 for ; Fri, 18 Jun 2021 13:31:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=OtoIKwAkT66XRKBPXvKRN0Azn+T9eWSZ2Zg428wY4wQ=; b=b0NCI7QnIWwW8zp/s2zR9qR+pqY9xaf97QUXnhcHLN09nvnMsrftqqHHzawJE6vDmn rQZcZBtqRidzWlCKndCbJEGrkS3hstjSVM3X6KecRVV06/btHBYZoE9bC+Ye/lf8tdHC 36E5SiFcO48ASju1C6ixq+uq8aF16zK59IZCjIAll/ccfg0VaedSMiGHrsCZH0eXaHZl NWeMLAA8E7cLWLUD/xvuvTODHXh5vUG2WxuPzckF5rvFOZmTkv2rH8Nj/tle0B3D0DHg 548o2JCF3L6rHoUBv+1yXRnoEeg/0T/BZy+LQ2ZzRA4Yw0F/O+JGYUlIIjZyebvui+4W P2Fw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=OtoIKwAkT66XRKBPXvKRN0Azn+T9eWSZ2Zg428wY4wQ=; b=f4xrchg5n2uD9S4jjxPbEuie9rEhJtS9a1PPgIlZksmSVmkOd7yZZRopgoyXn4rgdS 3ia/d381voCMz9usNAScqjAiRpBdLcVaSeiKFGsX3j2KoP6GguxAFztUbR96+bJaGmxQ kT/JfDFcUFLtCFZ1+Nj2SE7f1V8IboRldm8o/AfbIPUGZjMp2mzkRF48v/bx+4Erfu9X snWHGkONXmJmYyKNcIesqs4pN+ZZlvAxGRhPLPuZFyPiyHViLVLf0lJqQtGjdZwuiNOW 727T9Wut0COz9v7R+It0tmzcBQKGbQSwg6h3Ne8vtFCq4xvKa6f5sM0LDzLyN5odArA0 rGbg== X-Gm-Message-State: AOAM530v3aCmWoND6/d2ePnEBa2v9kIij7Qel5Qio/3GV5tkRIVZGF48 1GpESms9MCGJ3fQ7RbkOx7IhETpsvnJ1RQ== X-Google-Smtp-Source: ABdhPJwP+Dej6medo6thzYvUKRKGDEyMgJulAVbdRyLopnmT7Jvr86EP4VVH2JhOWIFhTn4/gaimlw== X-Received: by 2002:a9d:7a89:: with SMTP id l9mr11340938otn.124.1624048264293; Fri, 18 Jun 2021 13:31:04 -0700 (PDT) Received: from localhost (fixed-187-188-155-231.totalplay.net. [187.188.155.231]) by smtp.gmail.com with ESMTPSA id 16sm2225641otm.57.2021.06.18.13.31.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Jun 2021 13:31:04 -0700 (PDT) From: Felipe Contreras To: git@vger.kernel.org Cc: "brian m . carlson" , =?utf-8?q?Martin_?= =?utf-8?q?=C3=85gren?= , Bagas Sanjaya , Jeff King , Junio C Hamano Subject: [RFC/NOPATCHv3 3/4] doc: use XML-style escapes only for HTML and XML Date: Fri, 18 Jun 2021 15:30:56 -0500 Message-Id: <20210618203057.790320-4-felipe.contreras@gmail.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210618203057.790320-1-felipe.contreras@gmail.com> References: <20210618203057.790320-1-felipe.contreras@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: "brian m. carlson" Additionally, we don't want to use XML-style escapes for the litdd and plus macros, so let's only use the XML-style escapes in HTML and XML and use something different for our man pages. Signed-off-by: brian m. carlson --- Documentation/Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index d3103c3dde..53ef100a7a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -183,12 +183,15 @@ ASCIIDOC_HTML = xhtml5 ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +TXT_TO_HTML += -alitdd='&\#x2d;&\#x2d;' +TXT_TO_XML += -alitdd='&\#x2d;&\#x2d;' DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation XMLTO_EXTRA += -x manpage.xsl ifdef USE_ASCIIDOCTOR_MANPAGE TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage +TXT_TO_MAN += -aplus='+' +TXT_TO_MAN += -alitdd='\--' endif endif From patchwork Fri Jun 18 20:30:57 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Felipe Contreras X-Patchwork-Id: 12332151 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6EFC6C48BE8 for ; Fri, 18 Jun 2021 20:31:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 5A431613C2 for ; Fri, 18 Jun 2021 20:31:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233680AbhFRUdS (ORCPT ); Fri, 18 Jun 2021 16:33:18 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42590 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233669AbhFRUdR (ORCPT ); Fri, 18 Jun 2021 16:33:17 -0400 Received: from mail-oo1-xc29.google.com (mail-oo1-xc29.google.com [IPv6:2607:f8b0:4864:20::c29]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CFC2CC06175F for ; Fri, 18 Jun 2021 13:31:06 -0700 (PDT) Received: by mail-oo1-xc29.google.com with SMTP id k21-20020a4a2a150000b029024955603642so2756824oof.8 for ; Fri, 18 Jun 2021 13:31:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=vAuCKiY9Tdmxu6PI9f8mM1w1jAs4FdJcsuoP/22kCCg=; b=F3AqOx0sDj+49Yk/CHyYokzIi/kxXSiekkDaEg+Tsfq8iiuS7fuafXSR/6KqKaIlVq RkTGqS+O4+Buym1SmATIse7pWumd8PgW1gZNG5luI9zMJXf/R+huMaey1o4LTnnTH9H0 CF1YVib5xxiz+eKkE/FXJVuu6ClyUxYpqwq7V98ojVfnQRiSjrgU5mmSReuxKRGH2ZD7 5wGQUezbB9uS2jzjtN5DfCuDbJaEG1Dg+VagkiLDNQv4W4CEaLtU6S2Op3SmVqzWx4gR btJdzc0AuZeKDWBTYkbe9GsgG63yZ62heinLV0+Ydqj2b2T6v57kFTjiNwalAZUeuP1R VXRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=vAuCKiY9Tdmxu6PI9f8mM1w1jAs4FdJcsuoP/22kCCg=; b=VGuGPPNdsQyEz7PO9jC+T9t1VNRCDBN05jei+KrcDxHuLY000KZNBxfM7vUkcWEEVz S18TvJ+cKpIPrHeZTBtSALuvExWCXhA10wwuVa/M6HV2gdjkwJMn3sKTF60dGUWuIpVk lRjI/oQgixh70+bbE/jx4HTAG2ktAWsMlovkyDPJWCFWu0V6srjPknpqoW68eoXNabRn u5NqHfwdUCMZe7yeMFepOPn3v+OBeDkVRmmeJ7SiuCWbFmS8MXF1JMauPprJTMUNXUew 9DUr2FWkvCmU6z4D82yXDApUF6uUnXclWTbng3BaxgFHv8cTqH+suCBMq8ZaRUrGwdjL H3Aw== X-Gm-Message-State: AOAM5330fXNFtdUxA182dhVkLnvgo6/uOu0GU99N9yEJre+LkzMczUAA tf0sKe/wSwD6bK7WQ60Ko5KFlFqIECkEdg== X-Google-Smtp-Source: ABdhPJzojFVmrCXXyb0UVzjVce33LFhxiZlf14ggdjCh7JOHdwE186gae+9QWv+z5hx0MRDCHvtrbQ== X-Received: by 2002:a4a:6f0e:: with SMTP id h14mr10465908ooc.9.1624048266012; Fri, 18 Jun 2021 13:31:06 -0700 (PDT) Received: from localhost (fixed-187-188-155-231.totalplay.net. [187.188.155.231]) by smtp.gmail.com with ESMTPSA id h2sm2041723oog.16.2021.06.18.13.31.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Jun 2021 13:31:05 -0700 (PDT) From: Felipe Contreras To: git@vger.kernel.org Cc: "brian m . carlson" , =?utf-8?q?Martin_?= =?utf-8?q?=C3=85gren?= , Bagas Sanjaya , Jeff King , Junio C Hamano Subject: [RFC/NOPATCHv3 4/4] doc: remove GNU_ROFF option Date: Fri, 18 Jun 2021 15:30:57 -0500 Message-Id: <20210618203057.790320-5-felipe.contreras@gmail.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210618203057.790320-1-felipe.contreras@gmail.com> References: <20210618203057.790320-1-felipe.contreras@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: "brian m. carlson" By default, groff converts apostrophes in troff source to Unicode apostrophes. This is helpful and desirable when being used as a typesetter, since it makes the output much cleaner and more readable, but it is a problem in manual pages, since apostrophes are often used around shell commands and these should remain in their ASCII form for compatibility with the shell. Fortunately, the DocBook stylesheets contain a workaround for this case: they detect the special .g number register, which is set only when using groff, and they define a special macro for apostrophes based on whether or not it is set and use that macro to write out the proper character. As a result, the DocBook stylesheets handle all cases correctly automatically, whether the user is using groff or not, unlike our GNU_ROFF code. Additionally, this functionality was implemented in 2010. Since nobody is shipping a mainstream Linux distribution with security support that old anymore, we can just safely assume that the user has upgraded their system in the past decade and remove the GNU_ROFF option and its corresponding stylesheet altogether. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 8 -------- Documentation/manpage-quote-apos.xsl | 16 ---------------- Makefile | 4 ---- 3 files changed, 28 deletions(-) delete mode 100644 Documentation/manpage-quote-apos.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index 53ef100a7a..53a8fa9fd3 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -168,14 +168,6 @@ MAN_BASE_URL = file://$(htmldir)/ endif XMLTO_EXTRA += -m manpage-base-url.xsl -# If your target system uses GNU groff, it may try to render -# apostrophes as a "pretty" apostrophe using unicode. This breaks -# cut&paste, so you should set GNU_ROFF to force them to be ASCII -# apostrophes. Unfortunately does not work with non-GNU roff. -ifdef GNU_ROFF -XMLTO_EXTRA += -m manpage-quote-apos.xsl -endif - ifdef USE_ASCIIDOCTOR ASCIIDOC = asciidoctor ASCIIDOC_CONF = diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl deleted file mode 100644 index aeb8839f33..0000000000 --- a/Documentation/manpage-quote-apos.xsl +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - ' - \(aq - - - - diff --git a/Makefile b/Makefile index 48547e2c3b..98484ee88c 100644 --- a/Makefile +++ b/Makefile @@ -278,10 +278,6 @@ all:: # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks # field that counts the on-disk footprint in 512-byte blocks. # -# Define GNU_ROFF if your target system uses GNU groff. This forces -# apostrophes to be ASCII so that cut&pasting examples to the shell -# will work. -# # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the # documentation. #