Re: [sc-dev] [rfc] alternative documentation format, scwiki

[stefan kersten <steve@xxxxxxxxxx>]

On 2004-11-27 11:07:56 -0800, James McCartney wrote:
> 
> On Nov 27, 2004, at 10:17 AM, stefan kersten wrote:
> 
> >i'd really like to get the Document stuff including the
> >recent scwiki idea going on linux; emacs is too limited with
> >the current asynchronous approach. i've implemented the
> >beginnings of a gtk editor that displays RTF files decently
> >(well, much better than emacs), but writing an actual RTF
> >editing component would be quite a lot of work that could be
> >spent elsewhere.
> >
> >this has been discussed a few times before, and i think the
> >issue could be summarized like so:
> >
> >* ASCII is aesthetically inferior
> >* HTML is a no no
> >* XML is overkill
> >* LaTeX too
> >* remains RTF
> 
> It remains RTF so you can edit styled text directly and copy paste 
> between other apps and open the files in other apps.
> There is no drop-in WYSIWYG editor for or any other markup format. And 
> even if there was it would not be compatible with other apps on the 
> Mac.

these are valid points, but no show stoppers from my
pov. pasted markup can be converted on the fly, documents
can be exported to rtf.

> If the help files had to be human edited using markup, I think there 
> would be a lot less help.

i don't get the point. the difference is between grabbing
your mouse, selecting a range of text and pressing cmd-b
versus pressing cmd-e, adding * at the start of a phrase, *
at the end and pressing cmd-e again. my socialization must
be completely different ;)

> Linux needs a styled text format. Then rtf could be converted to that.

the problem is not converting rtf to text attributes in an
editor [1], but implementing UI logic for stuff like "the
bold toggle needs to get activated when i enter a region
that's bold" and, more importantly, generating 100%
compatible rtf files.

a simple example:

i can open and display a help file all right on linux if i
replace OSX font names either directly or in a font
configuration file. now i can stuff the font names used in a
document into a table and use that for font selection. but
what if the user wants "Nimbus Sans L" or "Bitsink Gloria
Mono"?

this is just a minor inconvenience per se, but an example of
throwing away structural information is the notorious
Help.help.rtf. the table of topics is realized using tabs;
now even with a suitable replacement font, fitting font size
and resolution, the tabs might get rendered incorrectly. if
i edit the file, insert new content with my font/tabwidth
ratio, things will look garbled on OSX.

don't get me wrong, i don't want to push an outlandish
solution for the pure fun of it, but i honestly think that
structured markup could make the documentation more
palleable on more platforms (WYSIWYM [2]). but if WYSIWYG
indeed is a requirement (is it?) we'll have to think of
something on linux ...

already thinking,
<sk>

[1] http://www.cs.tu-berlin.de/~kerstens/pub/SC-gtk-editor.png
[2] What You See Is What You Mean