A switch to restructured text
Kevin Dangoor
I'm going to suggest a switch to ReStructured Text from direct XHTML.
I think my reasons for originally suggesting WYSIWYG HTML were valid.
However, I think that there are good reasons to switch to ReST:
1. Uncontrolled XHTML would possibly have security issues
2. TinyMCE and Dojo's rich text widget don't seem to reliably do
XHTML (Dojo's, in fact, doesn't do XHTML at all)
At this point, I really need a working documentation tool for
TurboGears ASAP. Docudo is really close, but it's failing at basic
editing. ReST should be a predictable way to get the job done.
Kevin
p.s. I actually have a solid preference for Markdown, but ReST is
more powerful, secure and common in the Python community.
--
Kevin Dangoor
TurboGears / Zesty News
email: k...@blazingthings.com
company: http://www.BlazingThings.com
blog: http://www.BlueSkyOnMars.com
Mark Ramm
> I think my reasons for originally suggesting WYSIWYG HTML were valid.
> However, I think that there are good reasons to switch to ReST:
I think this is a good move. I agree about the benifits of WYSIWYG
and of Markdown, but I think using ReST is a win for the Docudo as a
widely used documentaiton tool for other Python projects.
And if it makes life easier for getting the TG docs moved over to
Docudo now, that's another huge benifit!
I'm looking forward to having some time to work on the core TurboGears
documentation, and having Docudo up would make it easier to do 10-15
min worth of work here and there.
--Mark
Max Ischenko
Mark wrote:
> I think this is a good move. I agree about the benifits of WYSIWYG
> and of Markdown, but I think using ReST is a win for the Docudo as a
> widely used documentaiton tool for other Python projects.
Kevin wrote:
> p.s. I actually have a solid preference for Markdown, but ReST is
> more powerful, secure and common in the Python community.
Interesting, but given a choice I prefer Markdown too.
How complex is to add another option to specify language markup of the source files?
Max.
Kevin Horn
It should be pretty easy to factor out certain parts of the Document object, and then maybe create a subclass for each document format you want to support, maybe using a factory function of wome kind to get the appropriate object. So you could have a XHTMLDocument, a ReSTDocument, a MarkdownDocument, a TextileDocument...whatever.
That said, I think we should focus on ReST, as I think it's more likely to be familiar to the Python community.
Kevin Horn
DISCLAIMER: I have no idea whatsoever what this will mean for the full text search functionality currently in Docudo. I don't _think_ it'll be a huge problem, but...
Max Ischenko
> It should be pretty easy to factor out certain parts of the Document
> object, and then maybe create a subclass for each document format you want
> to support, maybe using a factory function of wome kind to get the
> appropriate object. So you could have a XHTMLDocument, a ReSTDocument, a
> MarkdownDocument, a TextileDocument...whatever.
Or:
Document <-> Content:
format (e.g. xhtml, rest)
payload (actual text context here)
Max.
mikl
have something done. The current implementation are beyond frustrating
to use.
That besides, simplicity is good, and WYSIWYG is not simple ;)
Elvelind Grandin
Personally I prefer markdown over ReST but both beats a broken wysiwyg editor.
as for supporting more then one markup language (markdown, textile
etc). this would in theory by nice but you would have to be able
convert between them. so if somebody adds and page with markdown the
next person can edit it with textile. The problem is that support for
transforming xhtml to markupd text is very poor.
--
cheers
elvelind grandin
Kevin Dangoor
The thing about Markdown is that it, by design, allows any HTML,
which makes it less suitable for through-the-web editing. ReST lets
you do all kinds of crazy formatting without running arbitrary code.
Unfortunately, you have to do it in ReST's style...
Kevin
Guy Hulbert
> It's funny that I'm not the only one who prefers Markdown to ReST.
> The thing about Markdown is that it, by design, allows any HTML,
> which makes it less suitable for through-the-web editing. ReST lets
> you do all kinds of crazy formatting without running arbitrary code.
Why would you want to allow arbitrary formatting ?
[see below]
Why would you allow *any* formatting ?
Surely what you are interested in is the semantics. This is supposed to
be for documentation rather than marketing. Isn't it ?
>
> Unfortunately, you have to do it in ReST's style...
>
> Kevin
>
> On Aug 16, 2006, at 3:37 AM, Elvelind Grandin wrote:
>
> >
> > Great Kevin.
> > Personally I prefer markdown over ReST but both beats a broken
> > wysiwyg editor.
WYSIWYG is essential (eventually) unless you target a restricted
audience.
Is it not possible using AJAX/JSON to have a java-script front-end which
formats what the user types but sends format-free content to the backend
for storage?
Obviously this is a difficult problem but one could pick an existing
vocabulary (such as DocBook) and implement a small subset of it and then
incrementally add pieces of it. I realize this is probably beyond the
scope of what Docudo is aimed at but it is another way to think about
the problem.
> > as for supporting more then one markup language (markdown, textile
> > etc). this would in theory by nice but you would have to be able
> > convert between them. so if somebody adds and page with markdown the
> > next person can edit it with textile. The problem is that support
> for
> > transforming xhtml to markupd text is very poor.
--
--gh
Karl Guertin
> Why would you want to allow arbitrary formatting ?
> [see below]
markdown supplies an escape valve in the form of allowing raw html
within a markdown page. It's not a preference of anybody on this list,
it's a feature of the markup language.
> Why would you allow *any* formatting ?
I'm thinking he means structure like footnotes, tables, etc. instead
of colors, fonts, etc.
Guy Hulbert
> On 8/16/06, Guy Hulbert <gwhu...@eol.ca> wrote:
> > Why would you want to allow arbitrary formatting ?
> > [see below]
>
> markdown supplies an escape valve in the form of allowing raw html
> within a markdown page. It's not a preference of anybody on this list,
> it's a feature of the markup language.
I realize that [ see: "want to" ]. I understand Kevin's desire for
re-use of existing tools ... but once you start talking about ReST then
a lot more work is required ...
>
> > Why would you allow *any* formatting ?
> I'm thinking he means structure like footnotes, tables, etc. instead
> of colors, fonts, etc.
Hence DocBook and/or its ilk[1]. The DocBook tools I've looked at seem
to support subsets and it's better than re-inventing yet another wheel.
[1] I can't think of any 'ilk' really ... TeX/LaTeX still seems to be
the only reasonable choice for math ... you'd think in 20+ years someone
might have come up with something close.
>
> >
--
--gh
Karl Guertin
> Hence DocBook and/or its ilk[1]. The DocBook tools I've looked at seem
> to support subsets and it's better than re-inventing yet another wheel.
Dockbook sucks to write by hand and so you need some sort of editing
tool (be that an emacs mode or something more involved), which is the
sort of barrier to writing docs that Docudo seems to be trying to
avoid.
ReST (never tried to do markdown) is dead simple to integrate, you do
an import and one or two lines to do the docbook->html conversion.
I'd like to see wysiwyg editing, and admittedly that sort of thing is
supposed to be what I'm contributing to this project, but I've been
wayward in my TG/Docudo contributions since February.
Guy Hulbert
> Dockbook sucks to write by hand and so you need some sort of editing
> tool (be that an emacs mode or something more involved), which is the
> sort of barrier to writing docs that Docudo seems to be trying to
> avoid.
>
> ReST (never tried to do markdown) is dead simple to integrate, you do
> an import and one or two lines to do the docbook->html conversion.
Are you saying there is an ReST -> docbook tool or is this a typo ?
>
> I'd like to see wysiwyg editing, and admittedly that sort of thing is
I hate every wysiwyg tool I've ever used but I find DocBook (and earlier
incarnations) in emacs fairly painful as well. I find raw XML worse
than anything to edit but I haven't tried the emacs mode recently.
> supposed to be what I'm contributing to this project, but I've been
> wayward in my TG/Docudo contributions since February.
Still better than me ...
--
--gh
Jorge Vargas
I'm sorry if I'm not making sence.
but what's the problem with wikiformatting? can't we in some way import/integrate with lets say trac's wiki?
Kevin Dangoor
> but what's the problem with wikiformatting? can't we in some way
> import/integrate with lets say trac's wiki?
When it comes to text->HTML conversions, Markdown is my favorite. The
Trac/MoinMoin wiki style format is about equal, to my sense of
aesthetics, to ReST, but it's much less powerful (ie can represent
far fewer concepts while still being fairly readable/typeable text).
For those reasons, I'm more keen on ReST.
Kevin
Kevin Horn
The idea would be mostly just to give the user some more flexibility in setting up Docudo for their project. It isn't that relevant for our immediate purposes (i.e. TurboGears docs), I was just thinking ahead to the day when Docudo...dare I say it...Rules The World! :)
Kevin Horn