Remove info manual + remove shell tab copletion + improve radme and man page + m

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 100 insertions, 38 deletions

diff --git a/doc/man/gpp.1 b/gpp.1
index d7ba2e5..3a8fae3 100644
--- a/doc/man/gpp.1
+++ b/gpp.1
@@ -1,11 +1,14 @@
-.TH GPP 1 GPP
+.TH GPP 1 gpp
 .SH NAME
 gpp - Bash-based preprocessor for anything
-.PP
-gpp: General Preprocessor
+
 .SH SYNOPSIS
-.BR gpp
+.R gpp
 .RI [ OPTION ]...
+
+.SH ETYMOLOGY
+gpp stands for General Preprocessor.
+
 .SH DESCRIPTION
 .B gpp
 lets a developer embed directives written in
@@ -15,23 +18,35 @@ to automate the writting of parts of the document.
 .PP
 The preprocessing directives start with a symbol (or
 text string) specified by the developer. By default
-this symbol is \fB@\fP (at).
+this symbol is
+.B @
+(at).
 .PP
-Any line starting with \fB@<\fP (where \fB@\fP is
-the selected symbol for preprocessing directives)
-or \fB@>\fP, or is between a line starting with
-\fB@<\fP and a line starting with \fB@>\fP, is parsed
-as a line, written in
+Any line starting with 
+.B @< (where
+.B @
+is the selected symbol for preprocessing directives) or
+.BR @> ,
+or is between a line starting with
+.B @
+and a line starting with
+.BR @> ,
+is parsed as a line, written in
 .BR bash (1),
-that is executed during preprocessing. A \fB@<\fP
-line must have an associated \fB@>\fP line somewhere
-after it, all lines between them are parsed as
-preprocessing directives. A \fB@>\fP does however
-not need an associated \fB@<\fP line somewhere before
-it, making \fB@>\fP suitable for single line directives.
+that is executed during preprocessing. A
+.B @<
+line must have an associated
+.B @>
+line somewhere after it, all lines between them are
+parsed as preprocessing directives. A
+.B @>
+does however not need an associated
+.B @<
+line somewhere before it, making
+.B @>
+suitable for single line directives.
 .PP
-Preprocessing directives can also be inline. For this,
-use
+Preprocessing directives can also be inline. For this, use
 .BI @( COMMAND )
 where
 .I COMMAND
@@ -54,10 +69,9 @@ or
 .BI @{ VARIABLE ,,}
 for lowercase.
 .PP
-Everything that is not preprocessing directives is
-threaded as
-.BR echo (1):ed
-lines.
+Everything that is not a preprocessing directive is
+echo verbatim.
+
 .SH OPTIONS
 .TP
 .BR \-s ,\  \-\-symbol \ \fISYMBOL\fP
@@ -100,6 +114,69 @@ Print copyright notice and exit.
 .PP
 Short options must be joined. The value of a flag must
 be in a separate argument from the flag itself.
+
+.SH EXAMPLES
+.SS Conditional hello world
+This example only includes the
+.RB \(dq "Hello world" \(dq
+line if the environment variable
+.B HELLO
+is defined and is not empty.
+.PP
+.nf
+@>if [ -z "$HELLO" ]; the
+Hello world
+@>fi
+.fi
+
+.SS Mutliline preprocessor directive
+This example creates the function
+.BR uppercase ()
+that convert lower case ASCII leters to uper case.
+.PP
+.nf
+@<uppercase () {
+	lower=qwertyuiopasdfghjklzxcvbnm
+	upper=QWERTYUIOPASDFGHJKLZXCVBNM
+	sed y/$lower/$upper/ <<<"$*"
+@>}
+.fi
+
+.SS Inline directives
+This example uses the
+.BR uppercase ()
+function above to convert the user's username
+to upper case. If the user's username is
+.BR john ,
+the code will expand to
+.B You are logged in as JOHN.
+.PP
+.nf
+You are logged in as @(uppercase $USER).
+.fi
+
+.SS Variable expansions
+In this example, if the user's username
+.BR john ,
+the code will expand to
+.B You are logged in as john.
+.PP
+.nf
+You are logged in as @{USER}.
+.fi
+
+.SS Variable expansion with substitution
+This example uses a substitution mechanism in Bash to
+convert the first letter in a variable to upper case.
+In this example, if the user's username
+.BR john ,
+the code will expand to
+.B You are logged in as John.
+.PP
+.nf
+You are logged in as @{USER^}.
+.fi
+
 .SH RATIONALE
 Programmers need more automation when we write software
 and documentation. An unrestricted preprocessor lets
@@ -112,24 +189,9 @@ of the work.
 C is one of the few languages that includes a preprocessor,
 some times it is not enough; and all languages need
 preprocessors.
+
 .SH "SEE ALSO"
 .BR bash (1),
 .BR jpp (1),
 .BR cpp (1),
 .BR env (1)
-.PP
-Full documentation available locally via: info \(aq(gpp)\(aq
-.SH AUTHORS
-Principal author, Mattias Andrée.  See the COPYING file for the full
-list of authors.
-.SH LICENSE
-Copyright \(co 2013, 2014, 2015, 2017  Mattias Andrée
-.br
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-.br
-This is free software: you are free to change and redistribute it.
-.br
-There is NO WARRANTY, to the extent permitted by law.
-.SH BUGS
-Please report bugs to https://github.com/maandree/passcheck/issues or to
-maandree@member.fsf.org