search

crystal-lang / shards

Dependency manager for the Crystal language
Other
758 stars 99 forks source link

Rewrite manpages in asciidoc #253

Open ysbaddaden opened 5 years ago

ysbaddaden commented 5 years ago

It would be nice to rewrite the manpages in asciidoc and to build them using the asciidoctor gem. It's nicer to write in, and that would allow to have different output formats (man, html, md, ...). Git does that and I really like it.

straight-shoota commented 5 years ago

I've just manually transformed the man page to Markdown 😄 (crystal-lang/crystal-book#316). Having a single source format would definitely help to keep these instances in sync.

ZaWertun commented 3 years ago

Calling asciidoctor with empty SOURCE_DATE_EPOCH env variable gives this error:

SOURCE_DATE_EPOCH= asciidoctor -a shards_version=0.14.0 docs/shards.adoc -b manpage -o man/shards.1
asciidoctor: FAILED: /home/zawertun/tmp/shards/docs/shards.adoc: Failed to load AsciiDoc document - invalid value for Integer(): ""
Use --trace for backtrace

(I'm building shards from the tar.gz archive, not from the git repo)

straight-shoota commented 3 years ago

That makefile call is completely broken. Sorry, this was a really crappy copy and paste 😢

Fix is in #479.

szabgab commented 3 years ago

There are two man pages committed in the man/ that are removed when you run make clean. Should those be removed from the repository or are they still needed? If they are still needed then probably make clean should not remove them.

straight-shoota commented 3 years ago

For the time being, they're checked in as a convenience so you don't have to install asciidoctor to read the manpages.

So yeah, probably they shouldn't be cleaned. Feel free to make a PR. It's low priority, though.