Public SourceMage Discussion List

[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.

> > 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.

> 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.

Regards,

Remko van der Vossen

---

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}}

Attachment: pgp04fuyRzgAk.pgp
Description: PGP signature