#!/bin/cat

#? NAME
#?      usage_examples  - examples for advanced usage of o-saft.pl
#?
#? DESCRIPTION
#?      This file just contains examples and hints for advanced usage of
#?      o-saft.pl.
#?


###############################################################################
###
### Command completion
###

# Command and parameter completion exists for following shells:
#
#	shell	file to be used
#	-------+-------------------------
#	bash	bash_completion_o-saft
#	fish	fish_completion_o-saft
#	tcsh	tcsh_completion_o-saft
#	-------+-------------------------
#
# These files are located in the contrib/ directory. For installing and using
# them, please see the files itself and the shell's manual pages.


###############################################################################
###
### Postprocessing output
###

# All output is designed to be  easily  parsed by postprocessors. For details
# please see:

o-saft.pl --help=OUTPUT
o-saft.pl --help=RESULTS

# For converting (postprocessing)  the results to other formats,  some filter
# scripts are provided in the  contrib/  directory. The usage i.g. is like:
#	o-saft.pl ... | contrib/filter-script
# for example:

o-saft.pl +cipher --header --enabled your.tld | contrib/HTML-table.awk

# If you write your own filter script, it's probably best to use  o-saft.pl's
# --legacy=quick  option, which separates label and value by a TAB character.
# However, it should be still possible to parse the default format of the
# results, which is: 
#	Text of label:	TABvalue
# Where the  : (colon) terminates the label text, which is followed by spaces
# to align in columns, followed by a TAB character (aka \t aka 0x09) followed
# by the value (the result).
#
# For practical examples, please see  contrib/filter_examples .


###############################################################################
###
### Postprocessing output with colours
###

# To colourize the results, the script  contrib/bunt.pl  (or contrib/bunt.sh)
# can be used. It generates ANSI codes for the termnal. Example:

o-saft.pl some.tld +check | contrib/bunt.pl

# Sometimes colours need to be adapted, i.e. for red-green visual impairments
# or when a light background is used.

o-saft.pl some.tld +check | contrib/bunt.pl --blind
o-saft.pl some.tld +check | contrib/bunt.pl --purple

# If the  "aha - Ansi HTML Adapter"  (from https://github.com/theZiz/aha)  is
# available, the output can be converted to an HTML page:

o-saft.pl some.tld +check | contrib/bunt.pl | aha -w -b > some.tld_check.html


###############################################################################
###
### Generating a list with all possible commands
###

o-saft.pl --help=cmd

# same, but one command per line:

o-saft.pl --help=cmd --norc | awk 'BEGIN{i=4}{while (i<NF){print $i;i++}}' 

# generate list with  --cfg-data=CMD=  options (empty text):

o-saft.pl --help=cmd --norc \
| awk 'BEGIN{i=4}{while (i<NF){sub(/+/,"",$i);print "--cfg-data="$i"="i;i++}}' 


###############################################################################
###
### Redefine label texts in output
###

# To change the label (text) of a command, the option  --cfg-data=CMD=TEXT or
# --cfg-check=CMD=TEXT  can be used: 

o-saft.pl --help=cfg-data  --norc
o-saft.pl --help=cfg-check --norc

# This will  generate one line  --cfg-data=COMMAND=  foreach command.  Simply
# redirect this to for example  ./my-info-labels.txt  then add your new texts
# to each line in that file and use the file like:

o-saft.pl some.tld +info --rc=./my-info-labels.txt

# This feature can be used to translate the labels in other languages. There-
# for add the modified  ./my-info-labels.txt  to  .o-saft.pl   (which will be
# read automatically by  o-saft.pl).


###############################################################################
###
### Adding additional information (text) to the results
###

# o-saft.pl  writes a "hint" text for each  +check and for each  +info (data)
# command.  This is initially intended to give  additional informations about
# the performed checks.  Each such hint is written  in a separate line behind
# the corresponding info or check line.
# This feature can also be (mis-)used to add your own description to whatever
# check you want, simply by using the  option  --cfg-hint=CMD=TEXT . 
# A template file with all options for all possible commands can be generated
# as follows:

o-saft.pl --help=cmd --norc \
| awk 'BEGIN{i=4}{while (i<NF){sub(/+/,"",$i);print "--cfg-hint="$i"="i;i++}}' 

# Then proceed as describe for "Redefine label texts" above.

# Take care that this may overwrite existing hint texts.  Existing texts will
# be shown with:

o-saft.pl --help=cfg-hint --norc

###############################################################################
###
### Reading parameters from file or STDIN
###

# o-saft.pl does not support reading parameters (arguments and options) from
# STDIN, here-documents or redirected from a file. This behaviour is reserved
# for future functionality (reading data from STDIN etc.).
# However, o-saft.pl supports reading parameters from its RC-FILE ,see
#	o-saft.pl --help=CUSTOMIZATION
# this can be used to tweak reading prepared file.
#
# Example: file host-list.txt which contains host:port one per line:

o-saft.pl +cipher `awk -F: '/:/{print "--port="$2" --host="$1}' host-list.txt`



