Public SourceMage Discussion List

[David Kowis <dkowis AT shlrm.org>]

Quoting Remko van der Vossen <wich AT stack.nl>:

> On Tue, Sep 02, 2008 at 10:32:39AM +0200, Jaka Kranjc wrote:
> > On Tuesday 02 of September 2008 10:08:12 Remko van der Vossen wrote:
> > > I would very much be in favour of LaTeX documentation, there
> > > are quite a number of tools to create other forms from the LaTeX (html
> > > single page, multi page and framed, man pages, texinfo pages and txt) in
> > > addition to the regular dvi, ps and pdf.
> > There is no wiki with inherent latex syntax afaik. Without a wiki, we lose
> > public colaborative editing, don't we? A BLOCKER as any.
>
> I honestly don't think many people besides devs and a few active users
> actually contribute to the documentation, and really I feel that users
> who regularly contribute to the documentation should also be viewed as
> devs. So as long as we have a git repo all devs have access to I don't
> think there is that big of a problem really.
>
> btw, just a random though, does git make it possible to accept commits
> by anonymous users, but moderated by others? That would be a way for
> others to contribute, perhaps a bit more involved than a wiki, but I
> don't think anybody who would seriously want to contribute something to
> the docs would not be willing to use git to do so.

Sure, someone can clone the repo, build a patch and email it in. Trivial.

> > > I feel LaTeX is many times more transparent than wiki markup, I mean,
> > > what's easier to understand textbf{foobar} or '''foobar'''. It will
> > > only take a little to realise bf stands for boldface and once you know
> > > it you won't forget it because of the clear contextual link. In the case
> > > of wiki markup however I have to look up the insane markup each and and
> > > every time. And is most definately something that is holding me back
> > > from contributing more to the wiki/documentation.
> >
> > This is moinmoin's fault, some other wikis have a much more sensible syntax
> > ('''''for bold italic''''' is so ancient). moinmoin also has the help spread
> > out in various pages and there is no way to see the site map afaik.
> >
> > LaTeX isn't that transparent either. Ok, we could have a quick   
> > reference page
> > with all the common syntax, but imagine all the escaping / environments we
> > would need. If you use ^ (eg. repair files) or _ (every second spell file)
> > mathmode is turned on and things get formatted as equations.
>
> I don't think that's that big of an issue, most of these occurences are
> in special cases, (eg. the spell files you mention,) for which we could
> easily make commands. Furthermore most of the devs and even a large part
> of our userbase (as far as I am aware) are coders in some form or
> another, be it in shell scripting, some other form of scripting or a
> programming language, which means that most of us are already accustomed
> to escaping. And again large parts won't even need escaping, much of the
> documentation is simple text, which is no issue at all.

If most of the documentation is simple text, why bother with all the  
fancy goodness that LaTeX comes with anyway?

> > And sure, it can do custom commands, includes and quadratic wheels,  
> >  but do we
> > really need that?
>
> Of course you don't need it, you also don't need markup, we could do all
> the documentation in plain text, but it makes our lives easier. By using
> includes (or better yet input-s) we can make seperation of concerns,
> isolate certain topics and make the whole manageable, yet still being an
> integrated whole. And commands facilitate unification across our
> documentation, we won't have all kinds of versions of sourcemage/source
> mage/SourceMage/Source Mage/etc anymore we'll simply have a command
> sourcemage and always have the correct form everywhere, we'll simply
> have a spell command so that all spell names across all of the
> documentation is in the same markup. And of course we can make commands
> to lessen the burdens of escaping.

I'm not sure how it makes our lives easier. The capitalization issue  
mentioned above doesn't really bother me. It's not like we're a brand  
name. And I think having a whole pile of commands that "lessen the  
burdens" will just make things more difficult. It raises the bar to  
entry. Now people will have to learn LaTeX syntax (which, however  
simple, is intimidating). If we stick with the wiki, it's fairly  
trivial to either copy and paste something, or just look at the quick  
help page.

> P.S. some examples of how we could use commands:
>
> newcommand{spellfile}[1]{textbf{#1}}
> newcommand{prebuild}{spellfile{PRE_BUILD}}
> newcommand{build}{spellfile{BUILD}}
> newcommand{repairpostremove}[1]{spellfile{REPAIR^#1^POST_REMOVE}}
> newcommand{repairnonepostremove}{repairtrigger{none}}
> newcommand{repairallpostremove}{repairtrigger{all}}

I fail to see how that's simple and clean :/
I'm not even sure what it's doing. I'm not even sure why you'd want a  
... Oh, I get it now.

But this would only load in a spell file directly into the document.  
That almost never happens. This is like converting our spell syntax  
into LaTeX. Why would we even want to do that? We want to tell people  
how to write these things. And the only real requirement is that the  
"=" must line up ;) And a few other small things, but it's really  
pretty simple.

I think this is useful enough:

==Function Name==
{{{
Sample code
Pre formatted
}}}
This is a function that I just made up, and moin will put it in the  
table of contents, the sample code will be preformatted (and maybe  
syntax hilited) and I don't have to do any backslash madness, I don't  
need to do anything but look up the preformat syntax and the header  
syntax, and then I can go to town and write up an API document for my  
function.

And simpler!

All this aside, the root of the issue is that we don't need fancy,  
pretty documentation. We don't need advanced formatting capabilities.  
We don't need to add features to make it simpler. We need people to do  
it. We need people to be motivated enough to make it happen. There  
will probably not be any kind of standardization on the syntax we're  
going to use. If you want, build your documents in LaTeX. Then go  
learn python, and build a parser for MoinMoin to read LaTeX.

Or just go write up some documentation, or polish the ones we've got  
on the wiki. :P

--
David Kowis
Source Mage Linux - www.sourcemage.org
Liberty! - www.campaignforliberty.com

Attachment: pgpTmSaW1mbz6.pgp
Description: PGP Digital Signature