Formatting problem in Midgard documentation

[sonic-3]

Hi!

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

http://www.midgard-project.org/documentation/concepts-midcom-specs-components-styleguide/

Section Naming conventions - Classes for more examples.


Bye,

Andreas

--
Adding sound to movies would be like putting lipstick on the Venus de Milo. --
Mary Pickford, 1925

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Arttu Manninen]

Sonic wrote:
> Hi!

Hi, Andreas!

> 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
>
> http://www.midgard-project.org/documentation/concepts-midcom-specs-components-styleguide/
>
> Section Naming conventions - Classes for more examples.

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.

I have been correcting every time I see these mistakes. I have been
editing loads of old mgd_*** functions, but I haven't caught them all.
The same goes with other parts of the documentation.

Whenever you come across with similar mistakes, please send me the url
and I'll be correcting it.



--
Sincerely,
Arttu Manninen

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Torben Nehmer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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"

This will have the "a_function_name()" piece set in a monospaced font, the
common way to denote any programming constructs within normal text. See MRFC 26
for a few examples how this'll look.


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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (MingW32)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFEBZHEJPh4Kn6d5FYRAkwSAJ9kt/TUPfLEBSQZrIbn2MDxhY7nUQCdFmtW
k4cdTdfabSDf5y16snxjAY8=
=ut+k
-----END PGP SIGNATURE-----

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Henri Bergius]

On Mar 1, 2006, at 13:59, Arttu Manninen wrote:
> 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().

The PHP implementation of Markdown will be smarter about this when we  
upgrade to the version shipping with MidCOM 2.5...

http://www.michelf.com/projects/php-markdown/extra/#em

> Arttu Manninen

/Bergie

Henri Bergius
Consultant Partner, Nemein
henri.bergius@...

Midgard CMS
www.midgard-project.org




---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...