Skip to Content.
Sympa Menu

sm-discuss - Re: [SM-Discuss] Tome nominations

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: David Kowis <dkowis AT shlrm.org>
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] Tome nominations
  • Date: Tue, 02 Sep 2008 08:10:49 -0500

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




Archive powered by MHonArc 2.6.24.

Top of Page