Rust-lang community searches a successor for Markdown

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Rust-lang community searches a successor for Markdown

getreu
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
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

mojavelinux
Administrator
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
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

Jeremie Bresson
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.

Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
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).
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

ciampix
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

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

Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

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

https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

mojavelinux
Administrator
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
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
I forwarded your comment.
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
I started a new thread Rustdoc: Asciidoctor vs Markdown. Please contribute there with your experience!
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
@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]
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
Is anybody aware of a recent comparison between RestructuredText and Asciidoctor we could post to the above discussion?
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

johncarl81
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.
Reply | Threaded
Open this post in threaded view
|

Re: Rust-lang community searches a successor for Markdown

getreu
@johncarl81

I forwarded you suggestion.