From 1942b9bbefa663e7a2e693face84935d3a11f054 Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Sat, 18 Jan 2014 11:11:21 +0000 Subject: [PATCH] Re: [Patch v3 2/3] man: partial conversion to pod. --- 50/8ba3774faaa4effc6c87739787298280b6b9cb | 122 ++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 50/8ba3774faaa4effc6c87739787298280b6b9cb diff --git a/50/8ba3774faaa4effc6c87739787298280b6b9cb b/50/8ba3774faaa4effc6c87739787298280b6b9cb new file mode 100644 index 000000000..56cdf71f4 --- /dev/null +++ b/50/8ba3774faaa4effc6c87739787298280b6b9cb @@ -0,0 +1,122 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 3B33B431FC0 + for ; Sat, 18 Jan 2014 03:11:39 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -1.098 +X-Spam-Level: +X-Spam-Status: No, score=-1.098 tagged_above=-999 required=5 + tests=[DKIM_ADSP_CUSTOM_MED=0.001, FREEMAIL_FROM=0.001, + NML_ADSP_CUSTOM_MED=1.2, RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id YIg97gfxzCFK for ; + Sat, 18 Jan 2014 03:11:31 -0800 (PST) +Received: from mail2.qmul.ac.uk (mail2.qmul.ac.uk [138.37.6.6]) + (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 36B9A431FBD + for ; Sat, 18 Jan 2014 03:11:31 -0800 (PST) +Received: from smtp.qmul.ac.uk ([138.37.6.40]) + by mail2.qmul.ac.uk with esmtp (Exim 4.71) + (envelope-from ) + id 1W4ToA-0001Kq-Uq; Sat, 18 Jan 2014 11:11:23 +0000 +Received: from 93-97-24-31.zone5.bethere.co.uk ([93.97.24.31] helo=localhost) + by smtp.qmul.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.71) + (envelope-from ) + id 1W4ToA-00083E-J9; Sat, 18 Jan 2014 11:11:22 +0000 +From: Mark Walters +To: David Bremner , Jani Nikula , + notmuch@notmuchmail.org +Subject: Re: [Patch v3 2/3] man: partial conversion to pod. +In-Reply-To: <87bnzagyl3.fsf@zancas.localnet> +References: + <1389791332-21719-1-git-send-email-david@tethera.net> + <1389791332-21719-3-git-send-email-david@tethera.net> + <87lhyer3lf.fsf@nikula.org> <87bnzagyl3.fsf@zancas.localnet> +User-Agent: Notmuch/0.15.2+484~gfb59956 (http://notmuchmail.org) Emacs/23.4.1 + (x86_64-pc-linux-gnu) +Date: Sat, 18 Jan 2014 11:11:21 +0000 +Message-ID: <87vbxhczom.fsf@qmul.ac.uk> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +X-Sender-Host-Address: 93.97.24.31 +X-QM-Geographic: According to ripencc, + this message was delivered by a machine in Britain (UK) (GB). +X-QM-SPAM-Info: Sender has good ham record. :) +X-QM-Body-MD5: 9ec7034168ffabdb4ab0cf2657e36329 (of first 20000 bytes) +X-SpamAssassin-Score: 0.0 +X-SpamAssassin-SpamBar: / +X-SpamAssassin-Report: The QM spam filters have analysed this message to + determine if it is + spam. We require at least 5.0 points to mark a message as spam. + This message scored 0.0 points. Summary of the scoring: + * 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail + provider * (markwalters1009[at]gmail.com) + * 0.0 AWL AWL: From: address is in the auto white-list +X-QM-Scan-Virus: ClamAV says the message is clean +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Sat, 18 Jan 2014 11:11:39 -0000 + + +I don't have strong views on which format we use for docs. Html has the +nice feature that most people are happy writing it and making doc +writing simple seems a good idea. + +One negative for the pod2texi approach is that debian stable does not +have texinfo 5; to test this series I had to build the package from +source. + +Best wishes + +Mark + + + + + (html migh have an advantage that most people are happy writing it; eOn Fri, 17 Jan 2014, David Bremner wrote: +> Jani Nikula writes: +> +>> On Wed, 15 Jan 2014, David Bremner wrote: +>>> From: David Bremner +> +>> In short, I'm really tempted by using markdown as the format, not least +>> because it's what we use for the web pages. The big (also literally) +>> downside is pandoc (http://johnmacfarlane.net/pandoc/), the tool for +>> converting markdown to man. I don't mind its dependencies, others may +>> disagree. Are there any sensible alternatives to pandoc? +> +> To complicate things, if we did decide on something heavyweight I think +> I'd propose we think about rst instead of markdown. I don't rst as well +> as markdown, but markdown does feel a little too adhoc to me from time +> to time (e.g. a verbatim block forcing the end of a list and so on). +> As far as I can tell, there are many incompatible versions of markdown +> as soon as you start to want e.g. tables. +> +> In any case, rst -> man is supported by python-docutils. sphinx supports +> both man page generation and texinfo output. So that would be relatively +> lighter weight alternative (??) to pandoc. +> +> A more radical proposal would be to skip generating info and assuming +> everybody can browse html in emacs. That assumption is supposed to +> become less ludicrous in emacs24.4 with the inclusion of "eww". +> +> d +> _______________________________________________ +> notmuch mailing list +> notmuch@notmuchmail.org +> http://notmuchmail.org/mailman/listinfo/notmuch -- 2.26.2