Skip to main content

I'm thinking we could switch to another format for the #libcurl documentation: https://github.com/curl/curl/pull/12730

introducing "curldown" for libcurl man page format by bagder · Pull Request #12730 · curl/curl

curldown is this new file format for libcurl man pages. It is markdown inspired with differences: Each file has a set of leading headers with meta-data Supports a small subset of markdown cd2nrof...
GitHub
#libcurl
in reply to daniel:// stenberg://

Martin Peck
Martin Peck
• •
look good. Which bits of regular MD didn't you want to support?
in reply to Martin Peck

daniel:// stenberg://
daniel:// stenberg://
• •
@martinpeck Since this needs to render clean and nice man-pages, I rather just carefully add support for what we need and what we can make look good so I'm starting with just the basics
@Martin Peck
in reply to daniel:// stenberg://

Martin Peck
Martin Peck
• •

right...so, take what you need and nothing else? Makes sense. And would stripping/ignoring unwanted/unsupported stuff from a MD file be harder?

The reason I ask is partly editor support for MD is pretty good, so if users are editing something with a .md extension they get a bunch of stuff for free. Even GitHub will nicely render a .MD file for you.

I suspect your approach is a safer approach though. Just thinking out loud.

in reply to Martin Peck

daniel:// stenberg://
daniel:// stenberg://
• •
@martinpeck since I'm not really sure exactly how much I can/will support I did not really want to call it markdown... at least not yet
@Martin Peck
in reply to daniel:// stenberg://

Martin Peck
Martin Peck
• •
Yep. Understood. I think it's a good approach. As you say, plenty of casual contributors can edit MD-like docs.
in reply to daniel:// stenberg://

Tc001
Tc001
• •

Looks cool! Btw how does this differ from something like a yaml frontmatter? Can you have more than on in a page?

(sorry if a dumb question, I couldn't find any examples of the actual syntax)

in reply to Tc001

daniel:// stenberg://
daniel:// stenberg://
• •
@tc001 I don't know anything about what others do. =) But yes, that looks like a *very* similar format!
@Tc001
in reply to daniel:// stenberg://

Tc001
Tc001
• •
Nice, now i'm wondering if it could be directly fed into the existing tools that support that format to generate HTML docs from it as well... 🤔
Either way, good luck with the format, will be interesting to see how it pans out!
in reply to Tc001

daniel:// stenberg://
daniel:// stenberg://
• •
@tc001 we generate HTML directly from the man pages so that is already covered
@Tc001
in reply to daniel:// stenberg://

Wez Furlong :terminal:
Wez Furlong :terminal:
• •

big +1 on making it easier to contribute. I opted to skip man pages entirely in my more recent projects largely because I find that the *roffs are so unfriendly to use and maintain.

PS: scrolling through the PR I smiled when I got to the perl parts: definitely written by someone, like me, that did tech stuff in the 90's and early 00's 🙂

in reply to daniel:// stenberg://

daniel:// stenberg://
daniel:// stenberg://
• •
Merged! 47,000 lines changed...
in reply to daniel:// stenberg://

towo
towo
• •
Today from the "not without robust testing automation" department…
in reply to daniel:// stenberg://

Mark Eichin
Mark Eichin
• •
Neat! do you happen to have a comparison with ronn or pandoc ( https://jeromebelleman.gitlab.io/posts/publishing/manpages/ or https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/ ) or is it a simple enough subset that building up from the man pages you already had was good enough?

Authoring man pages in Markdown with Pandoc

man pages are one of the most tenacious forms of programmer-oriented documentation. These manual pages have changed relatively little since their first publication in 1971.
Eddie Antonio Santos (eddieantonio/blog)
in reply to Mark Eichin

daniel:// stenberg://
daniel:// stenberg://
• •
@eichin I wanted stronger integration and more control of the end result so that for example my website renders would remain functional
@Mark Eichin
in reply to Mangdries

daniel:// stenberg://
daniel:// stenberg://
• •
@Mangdries you're probably right, but I don't see how that PR is related...
@Mangdries
⇧