Daniel Carrera <[email protected]> writes:
> This is really frustrating. The math doesn't work with
> reST+gitit/pandoc. How can I document patch theory without subscripts
> and superscripts?
When I want to represent basic math in reST, I use Unicode's math
codepoints (e.g. ∑xⁿ⁺¹). For more complicated mathematics, there isn't
really a turn-key solution. I would have to look into writing TeX
snippets, including them verbatim in the TeX output, and compiling them
to MathML for the ODF and HTML output formats.
It sounds like you're working on patch theory documentation, which may
legitimately need complex math typesetting, columnar layouts, and end up
being too large for a single HTML document (the inter-section semantic
links prev/up/next you mentioned below). If that's the case, I suggest
putting that content into the manual (which is in LaTeX), and just
linking the wiki to the HTML output of that manual.
> I'm having a real issue with reST on gitit. You might list whatever
> theoretical features reST has, but those are useless if they are not
> implemented in gitit/pandoc. With markdown at least I can write math.
AFAIK, markdown "supports" mathematics by allowing users to insert raw
HTML. This has two key problems:
- you are locked into a single output format. You can't even produce
XHTML output anymore, let alone LaTeX. Secondly,
- authors are required to write syntactically correct HTML. If you
forget to close a tag, the output will be invalid. That means that
browsers in quirks mode will display something that MAY be correct
(or may not), and strictly compliant browsers will refuse to display
the content at all.
There are two other consequences:
- authors are tempted to insert arbitrary HTML even when it isn't
strictly necessary, particularly when they want to play typographer.
Your example below wanting to use <table> to enforce a layout of the
prev/up/next intersubsection links is a perfect example.
This means that all co-authors need to agree on the style of HTML
being inserted, and to use it consistently across all documents. A
new author needs to be educated about this style before she can
safely create documents. And if the style of that raw HTML is
changed, someone has to go through ALL extant documents and update
them individually, instead of just updating a single master style
file (be it .sty, .xslt or .css/pandoc).
- an author can *accidentally* insert raw HTML. The most common case
of this I've seen in markdown is where you innocently write a phrase
like
Never use /opt/<app name>/ if you can avoid it.
Because markdown adds the text "<app name>" VERBATIM into the source
document. Markdown users "work around" this by religiously tagging
everything they can find with `backticks`, which means literal text –
quite the opposite of a variable like <app name>.
I'm actually quite unhappy about you using .. raw:: html in the reST
sources, and I'm only acceding to it because pandoc's reST support is
indeed quite shit at present, and I hope it will improve in the short-
to mid-term.
> I use tables in the patch theory section for navigation ('Prev', 'Up'
> and 'Next' links) and for presentation (e.g. showing a patch on the
> left and its effect on the right, or showing a patch on the left, and
> its inverse on the right).
With respect, it sounds like you're obsessing about the presentation of
the document. That's not the author's job, it's the typesetter's job.
Your responsibility is to make sure that the text is there, not that
links "line up" or that text is arranged into columns.
In the context of the wiki, this means that you use what you have
available now, putting blocks one below the next. You add a comment
saying "I think this would look better in a columnar format", and then
you write an email to the pandoc/reST maintainer asking him to add table
support, pointing him at your document as an example.
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
