diff options
Diffstat (limited to '')
| -rw-r--r-- | gpp.1 (renamed from doc/man/gpp.1) | 138 |
1 files changed, 100 insertions, 38 deletions
@@ -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 |