Public SourceMage Discussion List

[Jaka Kranjc <smgl AT lynxlynx.info>]

On Tuesday 02 of September 2008 13:26:33 Remko van der Vossen wrote:
> On Tue, Sep 02, 2008 at 10:32:39AM +0200, Jaka Kranjc wrote:
> > 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.
Users we've never heard from contribute to the wiki. Even kids! :) And you 
don't have to contribute to documentation regularly to make it count. If 
someone does a wiki commit and then disappears, that's perfectly fine and 
even great (the contribution part).

> 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.
No, there would have to be another public repo. git is a lot more involved. 
You can't just point and click through your browser. And no extra porcelain 
would really help. I know git pretty well and would be put off if had to fix 
docs through it all the time.

You can use git and wiki together just fine anyway. I know my favourite wiki 
doesn't mind external edits and moinmoin possibly doesn't aswell. We'd just 
need to initialise a repository in the datadir and set it up. Then people can 
use both the wiki and git+$EDITOR to modify docs.

> > 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.
We have a documentation problem and we're not going to solve it by adding 
extra layers of complexity to the input system. We need all the help we can 
get, not just from experienced users that know how to code and use git. We 
try draft those sooner or later anyway. ;)

LP
-- 
We cannot command nature except by obeying her.  --Sir Francis Bacon
Have a sourcerous day! www.sourcemage.org