Where to put Ksh documentation?

[dnewhall]

Many years ago (circa-2010?), I taught some shell programming training. After that I expanded my notes to have all the Ksh93-specific features documented (since I was all-in on Ksh93 at the time). I've since found them and have expanded them even more from time to time for my own personal use. It's about 22 articles/topics and the word count is somewhere north of 10,000.

I'm feeling like these notes should be distributed somewhere since there's so little Ksh information out in the wild for new users. The question is where should these be placed.

Options:

1. Rework into some standard format (info? Markdown? Ksh's man format?) and distribute them with ksh93u+m: Requires buy-in from McDutchie, and would entail some serious reformatting, I think. Also, I'm not sure how to make things like my advice on, say, proper heredoc use be shoehorned into official-sounding documentation.

2. Dump everything into this project's wiki page: The wiki is there, but unused. But does anyone look at the wiki? Or is not looking at Github project wikis just a personal bias of mine?

3. Create a totally new webpage: Something like masteringkornshell dot something. It would boost search results for ksh (bash has a bajillion semi-official guides to it out there), but at the expense of maintaining another resource.

[rwmills]

I think that you should kill your 'wiki bias' and place them there.

Do you have anything on User Defined Types (typeset -T) that first appeared in 93t (I think). If you do then could you send me a copy?

[dannyweldon]

My suggestion is to format it in markdown and write a parser in ksh that can read that and output it in html and info. I have an incomplete parsing script that you could look at for inspiration. It can be in it's own separate repo and could then be installed as a separate package. You could develop this in your own repo and them perhaps it could eventually find it's way as a separate repo under this organisation.

[jghub]

markdown sure is viable. if document is hosted on github, html rendering of .md files sort of seems for "free", otherwise pandoc would come to my mind rather than writing a parser in ksh, though, for formatting the thing to different output formats?

but markdown is very limited in many respects. if I were to do something like this I very probably would choose https://asciidoctor.org instead. much much better/in a different class than good old markdown :).

and you are not alone: I find wikis usually not helpful. I prefer a structured document that I can browse in a "linear" way or even generate a decent pdf version of -- just like as with manpages.

[McDutchie]

There is a docs directory at the top level of the repository that was inherited from AT&T and has gone mostly unmaintained since. I don't have time to do anything with it. It would certainly be nice if someone were to step up to maintain and update that directory, and good quality new documentation would also be more than welcome. I'd be more than happy to accept pull requests to that end!

[dannyweldon]

I'd be more than happy to accept pull requests to that end!

Thank you!

@jghub Okay, asciidoctor looks good and a quick search says that Info docs can be produced by a two-step process by first converting to DockBook XML and then to Info. But note that this will require ruby to be installed for the documentation build which may or may not be a problem, as long as @McDutchie is okay with that. TBH, that's why I was thinking about using Markdown with a shell parser. Both Markdown and Asciidoc are supported by github syntax highlighting, which would make it easy for people to submit changes via a browser. @dnewhall it's up to you. I'd be happy to assist with reformatting, proof reading and re-organising. Your documentation could be integrated with the exiting web content in the docs folder.

Actually, bash documentation is written in Textinfo and converted to all the other format from that. Any thoughts on using that?

https://cgit.git.savannah.gnu.org/cgit/bash.git/tree/doc