My C-fu is pretty weak, occasionally write it in hobby code, but I’ve seen it done in projects from Suckless and code from the Vis editor, which are my references for ‘good c code’. Why do they recommend against it?
Linus spells out the Linux approach in these emails.
The short version is: don’t use a type abstraction where you don’t need one, nothing is wrong with typing ‘struct xxx’.
One of the emails in the link, on where typedefs are useful:
(a) totally opaque objects (where the typedef is actively used to _hide_
what the object is).
Example: "pte_t" etc opaque objects that you can only access using
the proper accessor functions.
NOTE! Opaqueness and "accessor functions" are not good in themselves.
The reason we have them for things like pte_t etc is that there
really is absolutely _zero_ portably accessible information there.
Worrying about performance is vastly overvalued. Good performance is a by-product of pursuing other goals, mainly simplicity.
This is largely true, based on my experience. Good advice to follow.
Do not use Markdown. [The essay referred to in the slides.]
I think the author is a bit harsh on Markdown, especially if you read the linked essay. It was designed for writing for the web, and was meant to be converted to HTML only. The author criticizes it for lacking things it was never meant to have.
But I do agree that it’s terrible for technical documentation and it’s a travesty that it’s become the norm in that respect. I recently switched to using Markdown for some internal documentation at work mostly because Bitbucket will render it and it (hopefully) encourages others on the team to write docs. When I’m writing with it, though, it’s a mess. No description lists, linking between things is ugly, and you have to manually make thing like a table of contents. I’d switch to mdoc but then I’m worried no one else will bother to writing anything. Maybe that will happen anyway with the cruddiness of Markdown, so perhaps it won’t matter.
(Bonus: in the linked essay, I learned that GNU is apparently going to kill off info. No arguments here!)
it’s a travesty that it’s become the norm in that respect
I believe we mostly have GitHub becoming the norm to thank for that. Its native formatting for rich presentation is Markdown via the README.md. With GitHub being massively adopted and Markdown being the least path of resistance, it’s hardly surprising how this came to be. So that hampers mdoc adoption.
Because everybody writes their documentation in README.md now (if at all), they also expect Markdown to man page converters. Those emit man(7) more or less by necessity. People unfamiliar with mandoc won’t care, but those that are may be annoyed by the semantic information that is lost. Not only because mandoc produces worse HTML output because of it, but also because mandoc’s semantic search won’t work for those man pages. However, the group that are unfamiliar with mandoc intersects more or less entirely with the group of people who writes Markdown exclusively. This further hampers mdoc adoption.
We have a man page and documentation problem. And there doesn’t seem to be a way to help it.
(Bonus: in the linked essay, I learned that GNU is apparently going to kill off info. No arguments here!)
Looks like that was from 2014 and I can’t tell if the proposed replacement is genuine or a very bad joke. Either way, it doesn’t feel like much has changed in 4 years unfortunately.
you have to manually make thing like a table of contents
This is a specific solution (VSCode specific), but I discovered markdown-toc recently and I like it. There are other tools that can be used to add a TOC to a markdown based on headings.
I actually find Markdown convenient for Readmes and user land documentation. Because I can get by with very little markup and the markup reads fine as text it encourages me to write.
I can totally see how it would be a pain for technical documentation for code bases, but I suspect you would use .rst and an assist from an automatic documentation generator for that.
I am regretting the Markdown choice already and I’ll probably switch to something else that can export Markdown so it can be read directly while browsing the repo.
So yeah, whether that’s .rst or not remains to be seen, but the pattern is the same.
texinfo(1) and DocBook are excessively complicated, ill-designed, and unmaintained
One might quibble with the complexity & design of texinfo, but I believe Brian Fox & Karl Berry would be surprised to find out that it’s unmaintained: they are, after all, the maintainers, and released the latest version last summer.
My C-fu is pretty weak, occasionally write it in hobby code, but I’ve seen it done in projects from Suckless and code from the Vis editor, which are my references for ‘good c code’. Why do they recommend against it?
Linus spells out the Linux approach in these emails.
The short version is: don’t use a type abstraction where you don’t need one, nothing is wrong with typing ‘struct xxx’.
One of the emails in the link, on where typedefs are useful:
Thanks, makes sense. Kudos for Linus for emphasizing tend. I
This is largely true, based on my experience. Good advice to follow.
I think the author is a bit harsh on Markdown, especially if you read the linked essay. It was designed for writing for the web, and was meant to be converted to HTML only. The author criticizes it for lacking things it was never meant to have.
But I do agree that it’s terrible for technical documentation and it’s a travesty that it’s become the norm in that respect. I recently switched to using Markdown for some internal documentation at work mostly because Bitbucket will render it and it (hopefully) encourages others on the team to write docs. When I’m writing with it, though, it’s a mess. No description lists, linking between things is ugly, and you have to manually make thing like a table of contents. I’d switch to mdoc but then I’m worried no one else will bother to writing anything. Maybe that will happen anyway with the cruddiness of Markdown, so perhaps it won’t matter.
(Bonus: in the linked essay, I learned that GNU is apparently going to kill off info. No arguments here!)
I believe we mostly have GitHub becoming the norm to thank for that. Its native formatting for rich presentation is Markdown via the
README.md. With GitHub being massively adopted and Markdown being the least path of resistance, it’s hardly surprising how this came to be. So that hampers mdoc adoption.Because everybody writes their documentation in
README.mdnow (if at all), they also expect Markdown to man page converters. Those emit man(7) more or less by necessity. People unfamiliar with mandoc won’t care, but those that are may be annoyed by the semantic information that is lost. Not only because mandoc produces worse HTML output because of it, but also because mandoc’s semantic search won’t work for those man pages. However, the group that are unfamiliar with mandoc intersects more or less entirely with the group of people who writes Markdown exclusively. This further hampers mdoc adoption.We have a man page and documentation problem. And there doesn’t seem to be a way to help it.
You’ve long been able to render AsciiDoc, org, rST, among other lightweight markup languages, to HTML with GitHub. For example:
I dunno why Markdown “won”, but maybe it had something to do with:
Looks like that was from 2014 and I can’t tell if the proposed replacement is genuine or a very bad joke. Either way, it doesn’t feel like much has changed in 4 years unfortunately.
This is a specific solution (VSCode specific), but I discovered markdown-toc recently and I like it. There are other tools that can be used to add a TOC to a markdown based on headings.
I actually find Markdown convenient for Readmes and user land documentation. Because I can get by with very little markup and the markup reads fine as text it encourages me to write.
I can totally see how it would be a pain for technical documentation for code bases, but I suspect you would use .rst and an assist from an automatic documentation generator for that.
I am regretting the Markdown choice already and I’ll probably switch to something else that can export Markdown so it can be read directly while browsing the repo.
So yeah, whether that’s .rst or not remains to be seen, but the pattern is the same.
One might quibble with the complexity & design of
texinfo, but I believe Brian Fox & Karl Berry would be surprised to find out that it’s unmaintained: they are, after all, the maintainers, and released the latest version last summer.