All of lore.kernel.org
 help / color / mirror / Atom feed
From: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: ksummit-discuss@lists.linuxfoundation.org
Subject: Re: [Ksummit-discuss] [CORE TOPIC] Documentation
Date: Wed, 5 Aug 2015 13:21:30 -0400	[thread overview]
Message-ID: <20150805172130.GB3061@gmail.com> (raw)
In-Reply-To: <55C242F4.7090005@gmail.com>

On Wed, Aug 05, 2015 at 07:08:04PM +0200, Michael Kerrisk (man-pages) wrote:
> I know even less about Sphinx, although its output capabilities,
> as described at http://sphinx-doc.org/index.html , seem interesting also.

Markdown has vastly simpler syntax than ReST, which has the upside of
being easier to learn, and the downside of being quite limited. I mean,
it doesn't even do tables unless you use an extended flavour
(GitHub-flavoured MarkDown).

For this reason I would recommend ReST over MD.

I find rst2man to be a great way to quickly write decent manpages. E.g.:

https://raw.githubusercontent.com/mricon/grokmirror/master/man/grok-pull.1.rst

Which generates the following man page:

https://raw.githubusercontent.com/mricon/grokmirror/master/man/grok-pull.1

Many will attest that the .rst source is a lot easier on the eyes than
final groff.

Hope this helps.

Best,
-- 
Konstantin Ryabitsev
Linux Foundation Collab Projects
Montréal, Québec

  parent reply	other threads:[~2015-08-05 17:21 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-08-01 14:41 [Ksummit-discuss] [CORE TOPIC] Documentation Jonathan Corbet
2015-08-02  7:07 ` Davidlohr Bueso
2015-08-03 13:35   ` Rafael J. Wysocki
2015-08-03 13:27     ` Konstantin Ryabitsev
2015-08-03 14:33     ` Jonathan Corbet
2015-08-03 20:45       ` Dmitry Torokhov
2015-08-04 10:59         ` Daniel Vetter
2015-08-04  0:52       ` Rafael J. Wysocki
2015-08-04 12:50       ` Laurent Pinchart
2015-08-04 13:03         ` Daniel Vetter
2015-08-04 14:28           ` Laurent Pinchart
2015-08-04 14:30             ` Daniel Vetter
2015-08-04 13:50         ` Dan Carpenter
2015-08-04 14:05           ` Geert Uytterhoeven
2015-08-04 14:29             ` Daniel Vetter
2015-08-04 14:30             ` Laurent Pinchart
2015-08-04 17:10               ` Geert Uytterhoeven
2015-08-04 14:42           ` Konstantin Ryabitsev
2015-08-04 18:21             ` Tim Bird
2015-08-04 21:00               ` Laurent Pinchart
2015-08-04 15:35         ` Mark Brown
2015-08-05 17:07           ` Michael Kerrisk (man-pages)
2015-08-04 17:24         ` Jonathan Corbet
2015-08-04  7:12 ` Michael Ellerman
2015-08-04  7:42   ` Marcel Holtmann
2015-08-04  8:33     ` Peter Huewe
2015-08-05 17:08       ` Michael Kerrisk (man-pages)
2015-08-05 17:19         ` josh
2015-08-05 17:21         ` Konstantin Ryabitsev [this message]
2015-08-04 12:54   ` Laurent Pinchart
2015-08-04 13:07     ` Daniel Vetter
2015-08-04 11:09 ` Daniel Vetter

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20150805172130.GB3061@gmail.com \
    --to=konstantin@linuxfoundation.org \
    --cc=ksummit-discuss@lists.linuxfoundation.org \
    --cc=mtk.manpages@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.