[PATCH 1/4] doc: use markdown tildes for code blocks
spitzak at gmail.com
Wed Dec 3 12:37:40 PST 2014
On 12/02/2014 07:45 PM, Peter Hutterer wrote:
> On Tue, Dec 02, 2014 at 06:29:33PM -0800, Bill Spitzak wrote:
>> This requires doxygen 1.8 or newer.
>> I could not figure out how to make configure.ac test the doxygen
>> version number. It appears to be really complex. So it will run with
>> any version of doxygen and the doc output is somewhat mangled.
> I'm missing the reasoning here: why not leave code/endcode? was this
> explained in some other thread?
The main reason is the \comment does not seem to work in code/endcode,
but works in the markdown. I also discovered that a code command breaks
the tilde version (by making it not remove the asterisks), so you have
to use all of one or the other consistently. Both of these are certainly
Another reason is that this is reverting a change I previously made.
Some people may prefer the markdown/wiki style rather than commands, as
it makes the comments more readable directly. Besides the tildes, the
same recent versions support indentation by 4 spaces to indicate code,
which is common in wiki markup. That may be another alternative.
I'm not sure if this is all enough of a reason however. As pointed out
by others this makes it not work with doxygen < 1.8 and there are
several systems that provide earlier versions by default, including
Ubuntu LTS 12.04. And I noticed in some libinput patches just posted
that code/endcode is used in them.
Any opinions? I don't know which way is better.
More information about the wayland-devel