Fossil Forum

ReStructuredText and PlantUML support
Login

ReStructuredText and PlantUML support

ReStructuredText and PlantUML support

(1) By anonymous on 2020-02-14 09:58:58 [link] [source]

Hi, are there any development plans, or any tip/suggestion, to integrate ReStructuredText documentation format and PlantUML diagrams into fossil?

https://en.wikipedia.org/wiki/ReStructuredText

https://en.wikipedia.org/wiki/PlantUML

Thanks in advance!

(2) By Warren Young (wyoung) on 2020-02-14 14:36:49 in reply to 1 [link] [source]

I dove into ReST for a while, intending to write a Lemon parser for it for addition to Fossil but then ran aground on the fact that you need to provide Lemon with a lexer. The question then becomes, how do you lex ReST? What are the lexical elements of a nearly free-form ASCII text document format?

Since I could only come up with wild guesses, and I didn't want to just try them all until one worked, I set the project aside.

(The wild guesses for those who want to try and proceed: a) just send the parser each byte in turn and let it figure things out; or b) break on every special character in ReST, then goto a).)

(3) By Offray (offray) on 2020-02-16 19:28:31 in reply to 1 [source]

As a workaround, you can use Markdeep in your Fossil repositories right now. It's not the Markup you're looking for, but you can use the Fossil's embedded doc feature to create good looking documentation with diagrams on it and even include the JS minified file in your repo, as a unversioned file. We have done that for several repos, like this ones:

Hope it helps,

(4) By Stephan Beal (stephan) on 2020-02-16 19:45:30 in reply to 3 [link] [source]

Hope it helps,

That (markdeep) is amazing. This is the first i have heard of it. Thank you for sharing.

(5) By Stephan Beal (stephan) on 2020-02-16 20:27:28 in reply to 3 [link] [source]

even include the JS minified file in your repo, as a unversioned file

Just FYI: you can easily serve the JS file and any CSS files directly from versioned content without any trickery. Search this fossil embedded doc page for baseurl/doc and baseurl/raw for several examples. That way anyone who clones your repo has all of the necessary pieces (in their current versions) automatically, without having to pull the unversioned files.

(6) By Offray (offray) on 2020-02-17 01:08:00 in reply to 5 [link] [source]

Thanks a lot Stephan.

I was thinking about unversioned files because a third party minified JS was kind of a binary that would not change that much, so I was thinking in some kind of script or command to pull the unversioned files. But the case you made with HighlightJS is good enough to look for something similar.

We will try something in that front soon and share here back.

Cheers,

(7.1) By Stephan Beal (stephan) on 2020-02-17 08:12:51 edited from 7.0 in reply to 3 [link] [source]

We have done that for several repos, like this ones: ... Hope it helps,

Markdeep is really interesting, providing more power than markdown while retaining (for the most part) its ease of use. i spent the past 2 hours or so experimentally porting an MD doc to it, and most of that time was spent bending the CSS to my will:

https://fossil.wanderinghorse.net/r/morbad-card-tools-s2cgi/doc/ckout/doc/index.html (edited for renamed link)

Resize the browser to see the table of contents move back and forth from the top of the doc to the sidebar. That's a killer feature. It could be done via CSS in plain markdown, but the ToC itself would have to be hand-generated, whereas markdeep does that automatically.

The only marginally annoying bit, when integrating it into a fossil repo, was getting the fossil page links working. e.g. a link like /finfo/foo.c only works if the repo lives at the top of its domain, which none of mine do. That has to be worked around by using relative links like ../../../finfo/foo.c. Not a big deal, only slightly ugly.

Thank you again, Offray!

(10) By Offray (offray) on 2020-02-17 16:57:36 in reply to 7.1 [link] [source]

You're welcomed Stephan... This kind of reciprocity maybe is just a way to say thanks again for the JSON API. :-)

Cheers,

Offray

(8) By anonymous on 2020-02-17 04:47:30 in reply to 3 [link] [source]

Markdeep looks very interesting, though all the documentation seems to be examples. Also, I wasn't able to find an actual specification for Markdeep.

Still, thanks.

(9) By Stephan Beal (stephan) on 2020-02-17 05:03:40 in reply to 8 [link] [source]

The spec is essentially the demo page, which, according to that page, acts as the demonstration of all features and as a test of its features.

It's essentially markdown plus a huge pile of extensions.