Asciidoctor :: Discussion

Rust-lang community searches a successor for Markdown

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

13 messages Options

getreu

Sep 19, 2016; 8:04pm

Rust-lang community searches a successor for Markdown

37 posts

Rust is a system programming language that will probably supersede C/C++. Their JavaDoc like documentation language called "RustDoc" and is based on Markdown-syntax.

Now the Rust community searches a successor for Markdown and discusses alternatives e.g. reStructuredText and AsciiDoc(tor), ...

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356

mojavelinux

Sep 24, 2016; 11:41pm

Re: Rust-lang community searches a successor for Markdown

Administrator

2681 posts

Thanks for sharing. That thread is a useful collection of criticisms of ReST, which we can consider when thinking about how to make AsciiDoc more approachable and flexible. It tells us what is important to writers.

- ReST is very picky and structured, unlike Markdown, and will break things in weird ways if you don't use three spaces in exactly the right place.

- Directives can behave strange and still often leave me unsure why my link isn't working.

- Title syntax is more annoying than Markdown (and more picky; title underlines only - and they have to be the same exact length as the phrase above them).

- Most implementations of ReST I've seen do a very bad job of telling you where and why your ReST is not working. Mostly, they just give you some semi-broken output.

For me, the key is consistency. It's important that the syntax for an image is the same as for a video and is the same as for a link. Once you get the pattern in your head, you know it works everywhere. Same for delimited blocks, etc. There are still some inconsistencies in AsciiDoc, but they can be addressed.

-Dan

On Mon, Sep 19, 2016 at 2:04 PM, getreu [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Rust is a system programming language that will probably supersede C/C++. Their JavaDoc like documentation language called "RustDoc" and is based on Markdown-syntax.

Now the Rust community searches a successor for Markdown and discusses alternatives e.g. reStructuredText and AsciiDoc(tor), ...

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Rust-lang-community-searches-a-successor-for-Markdown-tp4979.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Jeremie Bresson

Sep 28, 2016; 8:07am

Re: Rust-lang community searches a successor for Markdown

163 posts

In the discussion, I like this post:
https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/64

dch wrote

While I'm not a rust contributor I did implement Apache CouchDB's documentation and I learned a few things that might be helpful to you.
Most important is to be clear what you're trying to achieve. - you've got a book, a website, cargo - all of these have Requirements. You will need to compromise, so rank and score these. And make a timely decision.
1. What functionality is needed?
o markdown has limited advanced document functionality
o are cross-document references important?
o do you need to extend the syntax?
o do you need the same format across book, website, crates, stdlib?
2. Who is expected to write 90% of the docs? Does this tool/process make this really easy for them?
3. How easy is it for occasional contributors to send in something? Over time this is equally important.
4. Do you need a native toolchain today for this? I'm sure you'll end up writing your own eventually in Rust of course!

I would replace Point 4 with something like: does the doc-build integrate well with your existing setup, is the team familiar with the technology stack used by the doc-engine.

Answers to those questions is why we have chosen asciidoctor.

getreu

Sep 28, 2016; 6:56pm

Re: Rust-lang community searches a successor for Markdown

37 posts

I am Rust developer and I'd love to see Asciidoc(tor) in there.

I think it is a good moment for some lobbying. Thank you for your expertise.
I will collect your arguments and share them there. (This week-end).

ciampix

Sep 28, 2016; 7:10pm

Re: Rust-lang community searches a successor for Markdown

26 posts

On Wed, Sep 28, 2016 at 11:56:07AM -0700, getreu [via Asciidoctor :: Discussion] wrote:
>
>
> I am Rust developer and I'd love to see Asciidoc(tor) in there.
>
> I think it is a good moment for some lobbying. Thank you for your expertise.
> I will collect your arguments and share them there. (This week-end).
>

Then you may find the reason for KiCad docs went to asciidoc also interesting ...

https://github.com/KiCad/kicad-doc/tree/master/doc_alternatives

it is a bit outdated though...

--

Marco Ciampa

I know a joke about UDP, but you might not get it.

------------------------

GNU/Linux User #78271
FSFE fellow #364

------------------------

getreu

Sep 29, 2016; 4:44am

Re: Rust-lang community searches a successor for Markdown

37 posts

I posted some arguments for Asciidoc(tor). Please feel free to complete.

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356

mojavelinux

Sep 29, 2016; 6:44am

Re: Rust-lang community searches a successor for Markdown

Administrator

2681 posts

Keep in mind it's possible to add support for the Markdown link syntax using an inline macro extension.

-Dan

On Wed, Sep 28, 2016 at 10:44 PM, getreu [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I posted some arguments for Asciidoc(tor). Please feel free to complete.

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Rust-lang-community-searches-a-successor-for-Markdown-tp4979p5022.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

getreu

Sep 29, 2016; 3:56pm

Re: Rust-lang community searches a successor for Markdown

37 posts

I forwarded your comment.

getreu

Oct 06, 2016; 7:12am

Re: Rust-lang community searches a successor for Markdown

37 posts

I started a new thread Rustdoc: Asciidoctor vs Markdown. Please contribute there with your experience!

getreu

Oct 10, 2016; 8:13pm

Re: Rust-lang community searches a successor for Markdown

37 posts

@mojavelinux : Steve Klabnik is one of the Rust core team members at Mozilla:

https://internals.rust-lang.org/t/rustdoc-asciidoctor-vs-markdown/4161

[quote="steveklabnik, post:6, topic:4161, full:true"]
I'm not totally opposed to some sort of pluggable renderer for rustdoc, but I'm not sure who's gonna be willing to do the work, or how it'd work.
[/quote]

getreu

Oct 13, 2016; 5:10am

Re: Rust-lang community searches a successor for Markdown

37 posts

Is anybody aware of a recent comparison between RestructuredText and Asciidoctor we could post to the above discussion?

johncarl81

Oct 14, 2016; 9:08pm

Re: Rust-lang community searches a successor for Markdown

24 posts

If RustDoc is anything like JavaDoc, I'd heavily suggest checking out our Asciidoclet project:

https://github.com/asciidoctor/asciidoclet
http://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/
http://asciidoctor.org/news/2014/09/09/asciidoclet-1.5.0-released/

This was a super easy adaptation of Asciidoctor which has full access to the rich ecosystem of plugins. I love the ability to write inline UML and formatted code snippets with the minimal syntax requirements of Asciidoctor.

getreu

Oct 16, 2016; 2:55pm

Re: Rust-lang community searches a successor for Markdown

37 posts

@johncarl81

I forwarded you suggestion.