gen-readme.sh

   1 #!/bin/bash
   2 # Generate 'What does it do' README section
   3 # https://github.com/pyllyukko/user.js/
   4 # License: MIT
   5
   6 # Abort on error
   7 set -o errexit
   8
   9 ###################################
  10
  11 # Configuration:
  12 # Text used to generate/replace subsection headers
  13
  14 SECTION_HTML5_ID='HTML5 / APIs / DOM'
  15 SECTION_HTML5_MDOWN="HTML5 / [APIs](https://wiki.mozilla.org/WebAPI) / [DOM](https://en.wikipedia.org/wiki/Document_Object_Model) related settings. Mozilla is keen to implement every new HTML5 feature, which have had unforeseen security or privacy implications. This section disables many of those new and yet to be proven technologies."
  16
  17 SECTION_MISC_ID='Misc'
  18 SECTION_MISC_MDOWN="Settings that do not belong to other sections or are user specific preferences."
  19
  20 SECTION_EXTENSIONS_ID='Extensions / plugins'
  21 SECTION_EXTENSIONS_MDOWN="Harden preferences related to external plugins"
  22
  23 SECTION_FEATURES_ID='Firefox (anti-)features / components'
  24 SECTION_FEATURES_MDOWN="Disable Firefox integrated metrics/reporting/experiments, disable potentially insecure/invasive/[undesirable](https://en.wikipedia.org/wiki/Feature_creep) features"
  25
  26 SECTION_AUTOCONNECT_ID='Automatic connections'
  27 SECTION_AUTOCONNECT_MDOWN="Prevents the browser from [auto-connecting](https://support.mozilla.org/en-US/kb/how-stop-firefox-making-automatic-connections) to some Mozilla services, and from predictively opening connections to websites during browsing."
  28
  29 SECTION_HTTP_ID='HTTP'
  30 SECTION_HTTP_MDOWN="HTTP protocol related entries. This affects cookies, the user agent, referer and others."
  31
  32 SECTION_CACHING_ID='Caching'
  33 SECTION_CACHING_MDOWN="Enable and configure private browsing mode, don't store information locally during the browsing session"
  34
  35 SECTION_UI_ID='UI related'
  36 SECTION_UI_MDOWN="Improve visibility of security-related elements, mitigate shoulder-surfing"
  37
  38 SECTION_CRYPTO_ID='Cryptography'
  39 SECTION_CRYPTO_MDOWN="[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) protocol related settings"
  40
  41 SECTION_CIPHERS_ID='Cipher suites'
  42 SECTION_CIPHERS_MDOWN="This section tweaks the cipher suites used by Firefox. The idea is to support only the strongest ones with emphasis on [forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy), but without compromising compatibility with all those sites on the internet. As new crypto related flaws are discovered quite often, the cipher suites can be [tweaked to mitigate these newly discovered threats](https://github.com/pyllyukko/user.js/pull/18)."
  43
  44 ###################################
  45
  46 function _gen_entries() {
  47     # generate the "What does it do" README section from user.js PREF/SECTION fields and adjacent links
  48     grep -E --line-number "SECTION\:|PREF\:" user.js | grep -E -v '\(disabled\)' | sed -e 's/  \+\*//g' | \
  49     while read -r LINE; do
  50         LINENUM=$(echo "$LINE" | awk -F ':' '{ print $1 }')
  51         LINETYPE=$(echo "$LINE" | awk -F '[:/\*\ ]*' '{ print $2 }' 2>/dev/null)
  52         LINENAME=$(echo "$LINE" | sed -e 's/.*PREF\: //g; s/.*SECTION\: //g')
  53         if [ "$LINETYPE" = "SECTION" ]; then
  54             INDENT=''
  55             REF_LIST=''
  56             LINENAME=$(_gen_section_header "$LINENAME")
  57         else #if $LINETYPE = PREF
  58             # Build a list of reference links
  59             REF_LINE=$(( LINENUM + 1 ))
  60             REF_NUMBER=1
  61             REF_LIST=''
  62             # while next lines start with 'http', generate markdown links and append them to the list
  63             while sed "${REF_LINE}q;d" user.js | grep -E "^// http" >/dev/null; do
  64                 REF_URL=$(sed "${REF_LINE}q;d" user.js | cut -c4-) #
  65                 REF_MD_LINK="[${REF_NUMBER}](${REF_URL}) "
  66                 REF_LINE=$(( REF_LINE + 1 ))
  67                 REF_NUMBER=$(( REF_NUMBER + 1 ))
  68                 REF_LIST="${REF_LIST}${REF_MD_LINK}"
  69             done
  70             # if references list is not empty, add decoration chars [ ]
  71             if [ ! "$REF_LIST" = "" ]; then
  72                 REF_LIST=" [ ${REF_LIST}]"
  73             fi
  74             INDENT='* '
  75         fi
  76         MARKDOWNLINE="${INDENT}${LINENAME}${REF_LIST}"
  77         echo "$MARKDOWNLINE"
  78     done
  79 }
  80
  81 function _gen_section_header() {
  82     # generate section headers from a predefined list
  83     # replace section headers extracted from user.js with more detailed descriptions
  84     # in markdown format (configurable above)
  85     SECTION_NAME="$*"
  86     case "$SECTION_NAME" in
  87     "$SECTION_HTML5_ID")        echo -e "\n### ${SECTION_HTML5_ID}\n\n${SECTION_HTML5_MDOWN}\n" ;;
  88     "$SECTION_MISC_ID")         echo -e "\n### ${SECTION_MISC_ID}\n\n${SECTION_MISC_MDOWN}\n" ;;
  89     "$SECTION_EXTENSIONS_ID")   echo -e "\n### ${SECTION_EXTENSIONS_ID}\n\n${SECTION_EXTENSIONS_MDOWN}\n" ;;
  90     "$SECTION_FEATURES_ID")     echo -e "\n### ${SECTION_FEATURES_ID}\n\n${SECTION_FEATURES_MDOWN}\n" ;;
  91     "$SECTION_AUTOCONNECT_ID")  echo -e "\n### ${SECTION_AUTOCONNECT_ID}\n\n${SECTION_AUTOCONNECT_MDOWN}\n" ;;
  92     "$SECTION_HTTP_ID")         echo -e "\n### ${SECTION_HTTP_ID}\n\n${SECTION_HTTP_MDOWN}\n" ;;
  93     "$SECTION_CACHING_ID")      echo -e "\n### ${SECTION_CACHING_ID}\n\n${SECTION_CACHING_MDOWN}\n" ;;
  94     "$SECTION_UI_ID")           echo -e "\n### ${SECTION_UI_ID}\n\n${SECTION_UI_MDOWN}\n" ;;
  95     "$SECTION_CRYPTO_ID")       echo -e "\n### ${SECTION_CRYPTO_ID}\n\n${SECTION_CRYPTO_MDOWN}\n" ;;
  96     "$SECTION_CIPHERS_ID")      echo -e "\n### ${SECTION_CIPHERS_ID}\n\n${SECTION_CIPHERS_MDOWN}\n" ;;
  97     "*")                        echo -e "ERROR: unsupported section $SECTION_NAME"; exit 1 ;;
  98     esac
  99 }
 100
 101 function _gen_problems() {
 102     grep 'NOTICE:' user.js | sed 's|// NOTICE: |* |g'
 103 }
 104
 105 function _write_readme() {
 106     # write generated sections to README.md (section delimited by html comments BEGIN/END SECTION)
 107     # https://stackoverflow.com/questions/21876431
 108     echo "$README_SECTION" > whatdoesitdo.tmp.md
 109     awk '
 110     BEGIN             {p=1}
 111     /BEGIN SECTION/   {print;system("cat whatdoesitdo.tmp.md");p=0}
 112     /END SECTION/     {p=1}
 113     p' README.md > README-new.md
 114     mv README-new.md README.md
 115     rm whatdoesitdo.tmp.md
 116
 117
 118     echo "$PROBLEMS_SECTION" > knownproblems.tmp.md
 119     awk '
 120     BEGIN                          {p=1}
 121     /BEGIN PROBLEMS-LIMITATIONS/   {print;system("cat knownproblems.tmp.md");p=0}
 122     /END PROBLEMS-LIMITATIONS/     {p=1}
 123     p' README.md > README-new.md
 124     mv README-new.md README.md
 125     rm knownproblems.tmp.md
 126 }
 127
 128 ###################################
 129
 130 README_SECTION=$(_gen_entries)
 131 PROBLEMS_SECTION=$(_gen_problems)
 132 _write_readme