InfinityQuest - Programming Code Tutorials and Examples with Python, C++, Java, PHP, C#, JavaScript, Swift and more

Menu
  • Home
  • Sitemap

Python Programming Language Best Tutorials and Code Examples

Learn Python Right Now!
Home
Bash
Embedding Documentation in Shell Scripts in bash
Bash

Embedding Documentation in Shell Scripts in bash

InfinityCoder February 9, 2017

You want a simple way to provide formatted end-user documentation (e.g., man or html pages) for your script.

You want to keep both code and documentation markup in the same file to simplify updates, distribution, and revision control.

Embed documentation in the script using the “do nothing” built-in (a colon) and a here-document:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#!/usr/bin/env bash
# cookbook filename: embedded_documentation
 
echo 'Shell script code goes here'
 
# Use a : NOOP and here document to embed documentation,
: <<'END_OF_DOCS'
 
Embedded documentation such as Perl's Plain Old Documentation (POD),
or even plain text here.
 
Any accurate documentation is better than none at all.
 
Sample documentation in Perl's Plain Old Documentation (POD) format adapted from
CODE/ch07/Ch07.001_Best_Ex7.1 and 7.2 in Perl Best Practices.
 
=head1 NAME
 
MY~PROGRAM--One line description here
 
=head1 SYNOPSIS
 
  MY~PROGRAM [OPTIONS] <file>
 
=head1 OPTIONS
 
  -h = This usage.
  -v = Be verbose.
  -V = Show version, copyright and license information.
 
=head1 DESCRIPTION
 
A full description of the application and its features.
May include numerous subsections (i.e. =head2, =head3, etc.)
 
[...]
 
=head1 LICENSE AND COPYRIGHT
 
=cut
 
END_OF_DOCS

Then to extract and use that POD documentation, try these commands.

1
2
3
4
5
6
7
8
9
10
11
# To read on-screen, automatically paginated
$ perldoc myscript
 
# Just the "usage" sections
$ pod2usage myscript
 
# Create an HTML version
$ pod2html myscript > myscript.html
 
# Create a man page
$ pod2man myscript > myscript.1

Any plain text documentation or mark-up can be used this way, either interspersed throughout the code or better yet collected at the end of the script.

Since computer systems that have bash will probably also have Perl, its Plain Old Documentation (POD) may be a good choice.

Perl usually comes with pod2* programs to convert POD to HTML, LaTeX, man, text, and usage files.
Damian Conway’s Perl Best Practices (O’Reilly) has some excellent library module and application documentation templates that could be easily translated into any documentation format including plain text.

In that book, see CODE/ch07/Ch07.001_ Best_Ex7.1 and 7.2 in the examples tarball (http://examples.oreilly.com/perlbp/PBP_ code.tar.gz).
If you keep all of your embedded documentation at the very bottom of the script, you could also add an exit 0 right before the documentation begins.

That will simply exit the script rather than force the shell to parse each line looking for the end of the here-document, so it will be a little faster.

Thought, you need to be careful not to do that if you intersperse code and embedded documentation in the body of the script.

Share
Tweet
Email
Prev Article
Next Article

Related Articles

Branching Many Ways in bash
You have a series of comparisons to make, and the …

Branching Many Ways in bash

Saving Output from the ls Command in bash
You tried to save output from the ls command with …

Saving Output from the ls Command in bash

About The Author

InfinityCoder
InfinityCoder

Leave a Reply

Cancel reply

Recent Tutorials InfinityQuest

  • Adding New Features to bash Using Loadable Built-ins in bash
    Adding New Features to bash Using Loadable …
    June 27, 2017 0
  • Getting to the Bottom of Things in bash
    Getting to the Bottom of Things in …
    June 27, 2017 0

Recent Comments

  • fer on Turning a Dictionary into XML in Python
  • mahesh on Turning a Dictionary into XML in Python

Categories

  • Bash
  • PHP
  • Python
  • Uncategorized

InfinityQuest - Programming Code Tutorials and Examples with Python, C++, Java, PHP, C#, JavaScript, Swift and more

About Us

Start learning your desired programming language with InfinityQuest.com.

On our website you can access any tutorial that you want with video and code examples.

We are very happy and honored that InfinityQuest.com has been listed as a recommended learning website for students.

Popular Tags

binary data python CIDR convert string into datetime python create xml from dict python dictionary into xml python how to create xml with dict in Python how to write binary data in Python IP Address read binary data python tutorial string as date object python string to datetime python

Archives

  • June 2017
  • April 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
Copyright © 2021 InfinityQuest - Programming Code Tutorials and Examples with Python, C++, Java, PHP, C#, JavaScript, Swift and more
Programming Tutorials | Sitemap