☰

BashシェルスクリプトをMarkdownに変換するには？

tag-icon • tag-icon bash shell-script conversion markdown
BashシェルスクリプトをMarkdownに変換するには？

誰かが複数の配布スクリプトを書いていると想像してください。

これらのシェルスクリプトは注釈がたくさんあり、接続されており、人間が読めるように設計されています。

たとえば、README.mdまたはINSTALL.mdに変換してリポジトリにやさしくするのは便利ではありませんか？

なぜこれを行うことができますか？まず、重複する部分が多い可能性がある重複した労力を避けることができます。これも似合う単一真実原則

答え1

スクリプトでより一般的な文書の代わりにこの文書を使用すると、#他の形式の文書にシームレスに切り替えることができます。たとえば、

#!/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 DOC. 
"Quotes are " fine - and $params can be expanded if you 
don't quote the DOC delimiter.
DOC
... #shell script
... #more of same
: <<\DOC
- *Markdown Comment* -
    - or you can quote the delimiter and be more 
     free to use `backquotes` or whatever you like. 
     You can mark the comments up in markdown 
     in the first place, and print them w/ `"$0" -h`.
DOC

バラよりここのドキュメントのtldpの例19-2もっと学ぶ。

答え2

再作成しようとしているようです。強力な酸素。 DoxygenはMarkdownだけでなく、HTML、PDF、LaTeX、RTF、manページなども生成できます。

リリース時にdoxygenはシェルスクリプトを入力としてサポートしていませんが、カップル~の方法腕を使ってカウンターの位置にねじってみてください。

答え3

フォーマットに関係なく、プログラムの複雑な部分がどのように機能するかを説明する説明は、Readmeファイルにはほとんど表示されません。

-h呼び出しプログラムの出力をreadmeファイルまたはページとして使用するいくつかのパッケージがすでにありますman。たとえば、GNU人々を助けてくださいたとえば、これを行います。

IMO、シェルスクリプトが複雑すぎて広範なドキュメント（使用法やタスクの説明）が必要な場合は、Python / Perl / Rubyで書き直すことを検討する必要があります。

答え4

私は、スクリプトのソースコードから直接Markdownドキュメントを生成したいようです。私にとって、これはnowebと非常によく似ているようですが、nowebは（私が知っている限り）マークダウンをドキュメント形式でサポートしていません。ただし、そのサポートを追加することもできます。

関連情報