跳至主要内容

shelldoc 一个shell脚本文档系统

 A shell script documentation system

一个shell脚本文档系统

                __
               ▓#.▓▒
              ▓▓▓▓▒▒▒▒
              ▓▓▓
 ___/▓▓▓▓▓▓▓▒▒   ▏
<           ▒▒   ▏
 \ shelldoc  ▒  /
~~~~~~~~~~~~~~~~~~~~~~~

The shelldoc system provides a simple way to embed user documentation into Unix shell scripts. shelldoc is a Bourne shell compatible script that searches for specially formatted comments in text input (usually a Unix script file) on STDIN which are then emitted as the user documentation in reStructuredText format on STDOUT. All other code and standard comments within the source text are quietly ignored.shelldoc系统提供了一种将用户文档嵌入Unix shell脚本的简单方法。shelldoc是一个Bourne shell兼容的脚本，它在STDIN上搜索文本输入（通常是Unix脚本文件）中特殊格式的注释，然后在STDOUT上以reStructuredText格式作为用户文档发出。源文本中的所有其他代码和标准注释都将被忽略。

reStructuredText is a very lightweight form of markup that does not interfere with the human readability of the text. The Docutils project defnes the standard and provides filters to convert reStructuredText into html, latex (and on to PDF), and man format. Thus the same shelldoc documentation comments within a script can be extracted into a text file, a web page, a man page or a PDF file, covering all the main forms of electronic documentation.reStructuredText是一种非常轻量级的标记形式，它不会影响文本的可读性。Docutils项目定义了标准，并提供了将reStructuredText转换为html、latex（以及PDF）和man格式的过滤器。因此，脚本中相同的shelldoc文档注释可以提取到文本文件、网页、手册页或PDF文件中，涵盖所有主要形式的电子文档。

Other text documentation, such as README files, licenses and version histories can also be included in the source text as numbered appendices. This makes it possible to maintain and distrubute a single script file that contains all of its necessary user documentation.其他文本文档，如README文件、许可证和版本历史记录也可以作为编号的附录包含在源文本中。这使得维护和分发包含所有必要用户文档的单个脚本文件成为可能。

The shelldoc script file serves as full documentation, a "feature-complete" test of the shelldoc system and an example for usage of all features of the shelldoc syntax.shelldoc脚本文件作为完整的文档，是对shelldoc系统的一个“功能完整”的测试，也是一个使用shelldoc语法所有功能的示例。

Installation and use 安装与使用

Download the shelldoc script file and save it somewhere in your $PATH, for example:下载shelldoc脚本文件并将其保存在$PATH中，例如：

~/bin/shelldoc

then make sure that it is executable:然后确保它是可执行的：

chmod +x ~/bin/shelldoc

Then you can try the following commands to see how it works:然后你可以尝试下面的命令看看它是如何工作的：

# print shelldoc's documentation to the terminal:
shelldoc < shelldoc
# or view it as a manual page (requires Docutils):
shelldoc < shelldoc | rst2man | man -l -
# or save it as a web page (requires Docutils):
shelldoc < shelldoc | rst2html | shelldoc.html
# or save it as a plain text file:
shelldoc < shelldoc > shelldoc.txt
# view the licence:
shelldoc -a 1 < shelldoc
# save the version history:
shelldoc -a 2 < shelldoc > versions.txt
# save this readme file:
shelldoc -a 3 < shelldoc > README.md
# add a documentation template to another script:
shelldoc -t < myscript > mydocumentedscript
# strip documentation from a script:
shelldoc -s < mydocumentedscript > mycleanscript

Colophon 版本记录

The mascot of shelldoc is a Shelduck -- Tadorna tadorna (Linnaeus, 1758) -- a large and colourful duck found mainly in coastal areas across Eurasia. It nests in rabbit burrows or tree holes. The hatchlings leave the nest quickly and are led by their parents to nurseries on ponds lakes or rivers, often up to a mile away. There, they join other broods to form crêches of up to 100 young birds. A small number of adults stay behind to watch over these youngsters, while most of the parents fly off to join huge moulting flocks in coastal waters. These moulting flocks can contain many thousands of birds and are a spectacular sight on the Dutch and German Northern coast, as well as smaller gatherings on the Wash in England and the Firth of Forth in Scotland.shelldoc的吉祥物是一只鸭——Tadorna Tadorna （Linnaeus, 1758）——一种主要分布在欧亚大陆沿海地区的大型彩色鸭子。它在兔子洞或树洞里筑巢。幼鸟很快离开巢穴，由它们的父母带到一英里外的池塘、湖泊或河流上的托儿所。在那里，它们和其他幼鸟一起组成了crêches，有多达100只幼鸟。一小部分成年企鹅留下来照看这些幼崽，而大多数父母则飞到沿海水域加入庞大的换毛群。这些换羽的鸟群可以容纳成千上万只鸟，是荷兰和德国北部海岸的壮观景象，也是英格兰沃什和苏格兰福斯湾的小型聚会。
https://github.com/scripsi/shelldoc

评论

发表评论

此博客中的热门博文

Shell 文件包含

  和其他语言一样，Shell 也可以包含外部脚本。这样可以很方便的封装一些公用的代码作为一个独立的文件。 Shell 文件包含的语法格式如下： . filename # 注意点号(.)和文件名中间有一空格 或 source filename 实例 创建两个 shell 脚本文件。 test1.sh 代码如下： #!/bin/bash # author:菜鸟教程 # url:www.runoob.com url = "http://www.runoob.com" test2.sh 代码如下： #!/bin/bash # author:菜鸟教程 # url:www.runoob.com #使用 . 号来引用test1.sh 文件 . ./ test1 . sh # 或者使用以下包含文件代码 # source ./test1.sh echo "菜鸟教程官网地址：$url" 接下来，我们为 test2.sh 添加可执行权限并执行： $ chmod + x test2 . sh $ ./ test2 . sh 菜鸟教程官网地址： http : //www.runoob.com 注： 被包含的文件 test1.sh 不需要可执行权限。
发表评论
阅读全文

Shell 输入/输出重定向

  大多数 UNIX 系统命令从你的终端接受输入并将所产生的输出发送回​​到您的终端。一个命令通常从一个叫标准输入的地方读取输入，默认情况下，这恰好是你的终端。同样，一个命令通常将其输出写入到标准输出，默认情况下，这也是你的终端。 重定向命令列表如下： 命令 说明 command > file 将输出重定向到 file。 command < file 将输入重定向到 file。 command >> file 将输出以追加的方式重定向到 file。 n > file 将文件描述符为 n 的文件重定向到 file。 n >> file 将文件描述符为 n 的文件以追加的方式重定向到 file。 n >& m 将输出文件 m 和 n 合并。 n <& m 将输入文件 m 和 n 合并。 << tag 将开始标记 tag 和结束标记 tag 之间的内容作为输入。 需要注意的是文件描述符 0 通常是标准输入（STDIN），1 是标准输出（STDOUT），2 是标准错误输出（STDERR）。 输出重定向 重定向一般通过在命令间插入特定的符号来实现。特别的，这些符号的语法如下所示: command1 > file1 上面这个命令执行command1然后将输出的内容存入file1。 注意任何file1内的已经存在的内容将被新内容替代。如果要将新内容添加在文件末尾，请使用>>操作符。 实例 执行下面的 who 命令，它将命令的完整的输出重定向在用户文件中(users): $ who > users 执行后，并没有在终端输出信息，这是因为输出已被从默认的标准输出设备（终端）重定向到指定的文件。 你可以使用 cat 命令查看文件内容： $ cat users _mbsetupuser console Oct 31 17 : 35 tianqixin console Oct 31 17 : 35 tianqixin ttys000 Dec 1 11 : 33 输出重定向会覆盖文件内容，请看下面的例子： $ echo "菜鸟教程：www.runoob.com" > users $ cat users 菜鸟教程：...
发表评论
阅读全文

Shell 函数

  linux shell 可以用户定义函数，然后在shell脚本中可以随便调用。 shell中函数的定义格式如下： [   function   ]  funname  [ ( ) ] {     action;      [ return  int; ] } 说明： 1、可以带  function fun()  定义，也可以直接  fun()  定义,不带任何参数。 2、参数返回，可以显示加： return  返回，如果不加，将以最后一条命令运行结果，作为返回值。  return  后跟数值  n(0-255) . 下面的例子定义了一个函数并进行调用： 实例 #!/bin/bash # author:菜鸟教程 # url:www.runoob.com demoFun ( ) {      echo   "这是我的第一个 shell 函数!" } echo   "-----函数开始执行-----" demoFun echo   "-----函数执行完毕-----" 输出结果： -----函数开始执行----- 这是我的第一个 shell 函数! -----函数执行完毕----- 下面定义一个带有  return  语句的函数： 实例 #!/bin/bash # author:菜鸟教程 # url:www.runoob.com funWithReturn ( ) {      echo   "这个函数会对输入的两个数字进行相加运算..."      echo   "输入第一个数字: "      read  aNum      echo   "输入第二个数字: "      read  anotherNum      echo   "两个数字分别为  ...
发表评论
阅读全文