Re: Formatting problem in Midgard documentation
Torben Nehmer <
torben@...>
2006-03-01 12:21:24 GMT
Hi,
--Arttu Manninen wrote on 2006-03-01 12:59:
>> I've noticed this several times now and thought I'd post ist to the list:
>> There seems to de a formatting problem in Midgard's documentation pages,
>> which has the effect that underscores are not displayed, but converted to
>> <em> tags. This might be a feature, but in the case of class or method
>> names, it's a bug. For example get_current_leaf() is displayed as
>> getcurrentleaf() where "current" is written in italics. See
>
> This is both a bug that came along, when old 'de.linkm.taviewer'
> documentation was ported to 'net.nemein.wiki' documentation, and a possible
> mistake of document writers, I think.
>
> Wiki formatting sees underscore (_) as a start of italics unless an escape
> character has been used with it (\_). This means that get_current_leaf() will
> display as get<i>current</i>leaf().
>
> Functions and methods are easy to write wrong and when reading your own text,
> italics are still relatively easy to miss in a long text.
Yeah, this is a well-known problem nowadays, but not trivial to fix because, as
you say, these cases are not exactly easy to spot.
When we start fixing this, I recommend some different approach. Instead of
masking the underscores and thus having the function name set in normal type,
quote it using backticks, like this:
"some text with `a_function_name()` being mentioned"
(Continue reading)
: [ ] +1 Yes, I approve the proposal [ ] 0 I'm happy either way [ ] -1 No, I reject the proposal Live long and Prosper! Torben Nehmer -- Torben Nehmer, Guenzburg, Bavaria, Germany http://www.nathan-syntronics.de, mailto:torben@... PGP Public Key: https://www.link-m.de/pgp/t.nehmer.asc
RSS Feed