From: Mark Walters <markwalters1009@gmail.com>
To: David Bremner <david@tethera.net>, Jani Nikula <jani@nikula.org>,
	notmuch@notmuchmail.org
Subject: Re: [Patch v3 2/3] man: partial conversion to pod.
In-Reply-To: <87bnzagyl3.fsf@zancas.localnet>
References: <m2bnzeoiij.fsf@guru.guru-group.fi>
	<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
Precedence: list


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 <david@tethera.net> wrote:
> Jani Nikula <jani@nikula.org> writes:
>
>> On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote:
>>> From: David Bremner <bremner@debian.org>
>
>> 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