From ea24fe29968299ee68c70467ef4dd2cbc53bbee9 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 3 Aug 2016 07:55:54 +0200 Subject: [PATCH] INSTALL: Make the use of [, ], { and } consistent and explain it The diverse notations used in INSTALL are not as self explanatory as we might imagine, so let's attempt a consistent notation for mandatory and optional pieces of a command line, and to explain the meaning of each notation. This does away with the bash notation used in one spot, as it isn't universally understood and will only confuse the unknowing more. Reviewed-by: Rich Salz --- INSTALL | 92 +++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 19 deletions(-) diff --git a/INSTALL b/INSTALL index bdfa2bb0ae..ed7849e7cb 100644 --- a/INSTALL +++ b/INSTALL @@ -2,9 +2,8 @@ OPENSSL INSTALLATION -------------------- - [This document describes installation on all supported operating - systems (currently mainly the Linux/Unix family, OpenVMS and - Windows)] + This document describes installation on all supported operating + systems (the Linux/Unix family, OpenVMS and Windows) To install OpenSSL, you will need: @@ -23,6 +22,54 @@ * NOTES.WIN (any supported Windows) * NOTES.DJGPP (DOS platform with DJGPP) + Notational conventions in this document + --------------------------------------- + + Throughout this document, we use the following conventions in command + examples: + + $ command Any line starting with a dollar sign + ($) is a command line. + + { word1 | word2 | word3 } This denotes a mandatory choice, to be + replaced with one of the given words. + A simple example would be this: + + $ echo { FOO | BAR | COOKIE } + + which is to be understood as one of + these: + + $ echo FOO + - or - + $ echo BAR + - or - + $ echo COOKIE + + [ word1 | word2 | word3 ] Similar to { word1 | word2 | word3 } + except it's optional to give any of + those. In addition to the examples + above, this would also be valid: + + $ echo + + {{ target }} This denotes a mandatory word or + sequence of words of some sort. A + simple example would be this: + + $ type {{ filename }} + + which is to be understood to use the + command 'type' on some file name + determined by the user. + + [[ options ]] Similar to {{ target }}, but is + optional. + + Note that the notation assumes spaces around {, }, [, ], {{, }} and + [[, ]]. This is to differentiate from OpenVMS directory + specifications, which also use [ and ], but without spaces. + Quick Start ----------- @@ -49,7 +96,7 @@ $ nmake test $ nmake install - [If any of these steps fails, see section Installation in Detail below.] + If any of these steps fails, see section Installation in Detail below. This will build and install OpenSSL in the default location, which is: @@ -451,11 +498,11 @@ NOTE: This is not available on Windows. - $ ./config [options] # Unix + $ ./config [[ options ]] # Unix or - $ @config [options] ! OpenVMS + $ @config [[ options ]] ! OpenVMS For the remainder of this text, the Unix form will be used in all examples, please use the appropriate form for your platform. @@ -468,7 +515,7 @@ On some systems, you can include debugging information as follows: - $ ./config -d [options] + $ ./config -d [[ options ]] 1b. Configure OpenSSL for your operating system manually @@ -490,10 +537,10 @@ as the argument to Configure. For example, a "linux-elf" user would run: - $ ./Configure linux-elf [options] + $ ./Configure linux-elf [[ options ]] If your system isn't listed, you will have to create a configuration - file named Configurations/{something}.conf and add the correct + file named Configurations/{{ something }}.conf and add the correct configuration for your system. See the available configs as examples and read Configurations/README and Configurations/README.design for more information. @@ -517,29 +564,29 @@ $ mkdir /var/tmp/openssl-build $ cd /var/tmp/openssl-build - $ /PATH/TO/OPENSSL/SOURCE/config [options] + $ /PATH/TO/OPENSSL/SOURCE/config [[ options ]] or - $ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options] + $ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]] OpenVMS example: $ set default sys$login: $ create/dir [.tmp.openssl-build] $ set default [.tmp.openssl-build] - $ @[PATH.TO.OPENSSL.SOURCE]config {options} + $ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]] or - $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options} + $ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]] Windows example: $ C: $ mkdir \temp-openssl $ cd \temp-openssl - $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options} + $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]] Paths can be relative just as well as absolute. Configure will do its best to translate them to relative paths whenever possible. @@ -568,8 +615,8 @@ tracker. Maybe the bug was already reported or has already been fixed. - [If you encounter assembler error messages, try the "no-asm" - configuration option as an immediate fix.] + (If you encounter assembler error messages, try the "no-asm" + configuration option as an immediate fix.) Compiling parts of OpenSSL with gcc and others with the system compiler will result in unresolved symbols on some systems. @@ -640,9 +687,16 @@ or libssl. lib Contains the OpenSSL library files. lib/engines Contains the OpenSSL dynamically loadable engines. - share/man/{man1,man3,man5,man7} - Contains the OpenSSL man-pages. - share/doc/openssl/html/{man1,man3,man5,man7} + + share/man/man1 Contains the OpenSSL command line man-pages. + share/man/man3 Contains the OpenSSL library calls man-pages. + share/man/man5 Contains the OpenSSL configuration format man-pages. + share/man/man7 Contains the OpenSSL other misc man-pages. + + share/doc/openssl/html/man1 + share/doc/openssl/html/man3 + share/doc/openssl/html/man5 + share/doc/openssl/html/man7 Contains the HTML rendition of the man-pages. OpenVMS ('arch' is replaced with the architecture name, "Alpha" -- 2.34.1