11–20 of 34 posts
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.
Earlier quoted context omitted.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
>Embed HTML (more or less preferred, depending on your situation) But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use tags, but then you lose syntax highlighting. Actually I've always wondered why no MD renderer supports something like which it then treats the same as a ```js code block. Or a pseudo element...
Earlier quoted context omitted.
Not because of Programmers who think that the time spent writing documentation would be better spent programming some more? ;)
No reason it couldn't be both, I suppose.
And then documentation, where it exists, is often poorly CM'd word documents, and poorly OCR'd PDFs (or doc->pdf that somehow lost the ability to be searchable and selectable text, what option did they select?!?).
The offending systems are only maintainable because a few people haven't retired (< 1 year left for several of them) and sheer force of will for the rest of us.
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.
You can `make mandocs` in the linux tree, then `make installmandocs` to make them easily accessible with the man command, i.e. `man struct_sk_buff` will display the definition of an sk_buff.
Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.
Earlier quoted context omitted.
>Embed HTML (more or less preferred, depending on your situation) But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use tags, but then you lose syntax highlighting. Actually I've always wondered why no MD renderer supports something like which it then treats the same as a ```js code block. Or a pseudo element...
Kramdown supports this with markdown="1" as an attribute on html tags: http://kramdown.gettalong.org/syntax.html#html-blocks
```js
console.log("Hello, world!");
```
VSCode's markdown preview renderer ( https://github.com/markdown-it/markdown-it ) implements CommonMark, so I'm very happy right now :)
Earlier quoted context omitted.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
>Embed HTML (more or less preferred, depending on your situation) But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use tags, but then you lose syntax highlighting. Actually I've always wondered why no MD renderer supports something like which it then treats the same as a ```js code block. Or a pseudo element...
tags, but then you lose syntax highlighting.Pandoc supports this with the `markdown_in_html_blocks` option.
Earlier quoted context omitted.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
3. Pick a language that already supports it and is stable, standardized, without having to whip out some specialized version just for your codebase.