New answers tagged conversion
Using here-documents in scripts as opposed to the more common # can make for smooth transition to other forms of documentation. For example: #!/bin/sh case $1 in (*-h*) sed '/^:/,/^DOC/!d;s/^:/cat/' "$0" |sh -s "$@" exit;;esac : <<DOC Enter as many lines of documentation as you might need - just don't begin any but the first with : or the last with ...
It sounds like you're trying to reinvent Doxygen. Doxygen can create not only Markdown but also HTML, PDF, LaTeX, RTF, man pages, and more. As shipped, Doxygen doesn't support shell scripts as input, but there are a couple of ways to arm-twist it into coping.
Comments explaining how a complicated parts of a program works seldom have no place in a readme, whatever format. There already are packages where the output of calling a program with -h is used as readme or as man page. E.g. GNU help2man e.g. does this. IMO, if you shell scripts become so complicated that they need heavy documentation (either to explain ...
Top 50 recent answers are included