diff options
| -rw-r--r-- | bash.html.markdown | 70 | ||||
| -rw-r--r-- | perl6-pod.html.markdown | 619 |
2 files changed, 659 insertions, 30 deletions
diff --git a/bash.html.markdown b/bash.html.markdown index 8c40931e..0385c46d 100644 --- a/bash.html.markdown +++ b/bash.html.markdown @@ -20,21 +20,23 @@ contributors: filename: LearnBash.sh --- -Bash is a name of the unix shell, which was also distributed as the shell for the GNU operating system and as default shell on Linux and Mac OS X. -Nearly all examples below can be a part of a shell script or executed directly in the shell. +Bash is a name of the unix shell, which was also distributed as the shell +for the GNU operating system and as default shell on Linux and Mac OS X. +Nearly all examples below can be a part of a shell script +or executed directly in the shell. [Read more here.](http://www.gnu.org/software/bash/manual/bashref.html) ```bash #!/usr/bin/env bash -# First line of the script is shebang which tells the system how to execute +# First line of the script is the shebang which tells the system how to execute # the script: http://en.wikipedia.org/wiki/Shebang_(Unix) # As you already figured, comments start with #. Shebang is also a comment. # Simple hello world example: echo Hello world! # => Hello world! -# Each command starts on a new line, or after semicolon: +# Each command starts on a new line, or after a semicolon: echo 'This is the first line'; echo 'This is the second line' # => This is the first line # => This is the second line @@ -47,7 +49,7 @@ Variable = "Some string" # => returns error "Variable: command not found" # Bash will decide that Variable is a command it must execute and give an error # because it can't be found. -# Or like this: +# Nor like this: Variable= 'Some string' # => returns error: "Some string: command not found" # Bash will decide that 'Some string' is a command it must execute and give an # error because it can't be found. (In this case the 'Variable=' part is seen @@ -65,8 +67,9 @@ echo '$Variable' # => $Variable # Parameter expansion ${ }: echo ${Variable} # => Some string # This is a simple usage of parameter expansion -# Parameter Expansion gets a value from a variable. It "expands" or prints the value -# During the expansion time the value or parameter are able to be modified +# Parameter Expansion gets a value from a variable. +# It "expands" or prints the value +# During the expansion time the value or parameter can be modified # Below are other modifications that add onto this expansion # String substitution in variables @@ -114,8 +117,8 @@ echo {1..10} # => 1 2 3 4 5 6 7 8 9 10 echo {a..z} # => a b c d e f g h i j k l m n o p q r s t u v w x y z # This will output the range from the start value to the end value -# Builtin variables: -# There are some useful builtin variables, like +# Built-in variables: +# There are some useful built-in variables, like echo "Last program's return value: $?" echo "Script's PID: $$" echo "Number of arguments passed to script: $#" @@ -127,7 +130,7 @@ echo "Script's arguments separated into different variables: $1 $2..." # Our current directory is available through the command `pwd`. # `pwd` stands for "print working directory". -# We can also use the builtin variable `$PWD`. +# We can also use the built-in variable `$PWD`. # Observe that the following are equivalent: echo "I'm in $(pwd)" # execs `pwd` and interpolates output echo "I'm in $PWD" # interpolates the variable @@ -143,7 +146,7 @@ read Name # Note that we didn't need to declare a new variable echo Hello, $Name! # We have the usual if structure: -# use 'man test' for more info about conditionals +# use `man test` for more info about conditionals if [ $Name != $USER ] then echo "Your name isn't your username" @@ -180,7 +183,7 @@ then echo "This will run if $Name is Daniya OR Zach." fi -# There is also the =~ operator, which tests a string against a Regex pattern: +# There is also the `=~` operator, which tests a string against a Regex pattern: Email=me@example.com if [[ "$Email" =~ [a-z]+@[a-z]{2,}\.(com|net|org) ]] then @@ -190,9 +193,9 @@ fi # which are subtly different from single [ ]. # See http://www.gnu.org/software/bash/manual/bashref.html#Conditional-Constructs for more on this. -# Redefine command 'ping' as alias to send only 5 packets +# Redefine command `ping` as alias to send only 5 packets alias ping='ping -c 5' -# Escape alias and use command with this name instead +# Escape the alias and use command with this name instead \ping 192.168.1.1 # Print all aliases alias -p @@ -205,14 +208,14 @@ echo $(( 10 + 5 )) # => 15 # directory with the ls command: ls # Lists the files and subdirectories contained in the current directory -# These commands have options that control their execution: +# This command has options that control its execution: ls -l # Lists every file and directory on a separate line ls -t # Sorts the directory contents by last-modified date (descending) ls -R # Recursively `ls` this directory and all of its subdirectories # Results of the previous command can be passed to the next command as input. -# grep command filters the input with provided patterns. That's how we can list -# .txt files in the current directory: +# The `grep` command filters the input with provided patterns. +# That's how we can list .txt files in the current directory: ls -l | grep "\.txt" # Use `cat` to print files to stdout: @@ -280,10 +283,17 @@ EOF # Run the hello.py Python script with various stdin, stdout, and # stderr redirections: python hello.py < "input.in" # pass input.in as input to the script + python hello.py > "output.out" # redirect output from the script to output.out + python hello.py 2> "error.err" # redirect error output to error.err -python hello.py > "output-and-error.log" 2>&1 # redirect both output and errors to output-and-error.log -python hello.py > /dev/null 2>&1 # redirect all output and errors to the black hole, /dev/null, i.e., no output + +python hello.py > "output-and-error.log" 2>&1 +# redirect both output and errors to output-and-error.log + +python hello.py > /dev/null 2>&1 +# redirect all output and errors to the black hole, /dev/null, i.e., no output + # The output error will overwrite the file if it exists, # if you want to append instead, use ">>": python hello.py >> "output.out" 2>> "error.err" @@ -312,11 +322,11 @@ rm -r tempDir/ # recursively delete # current directory. echo "There are $(ls | wc -l) items here." -# The same can be done using backticks `` but they can't be nested - the preferred way -# is to use $( ). +# The same can be done using backticks `` but they can't be nested - +#the preferred way is to use $( ). echo "There are `ls | wc -l` items here." -# Bash uses a case statement that works similarly to switch in Java and C++: +# Bash uses a `case` statement that works similarly to switch in Java and C++: case "$Variable" in #List patterns for the conditions you want to meet 0) echo "There is a zero.";; @@ -324,7 +334,7 @@ case "$Variable" in *) echo "It is not null.";; esac -# for loops iterate for as many arguments given: +# `for` loops iterate for as many arguments given: # The contents of $Variable is printed three times. for Variable in {1..3} do @@ -345,14 +355,14 @@ done # => 3 # They can also be used to act on files.. -# This will run the command 'cat' on file1 and file2 +# This will run the command `cat` on file1 and file2 for Variable in file1 file2 do cat "$Variable" done # ..or the output from a command -# This will cat the output from ls. +# This will `cat` the output from `ls`. for Output in $(ls) do cat "$Output" @@ -432,8 +442,8 @@ grep "^foo.*bar$" file.txt | grep -v "baz" # and not the regex, use fgrep (or grep -F) fgrep "foobar" file.txt -# The trap command allows you to execute a command whenever your script -# receives a signal. Here, trap will execute `rm` if it receives any of the +# The `trap` command allows you to execute a command whenever your script +# receives a signal. Here, `trap` will execute `rm` if it receives any of the # three listed signals. trap "rm $TEMP_FILE; exit" SIGHUP SIGINT SIGTERM @@ -442,7 +452,7 @@ NAME1=$(whoami) NAME2=$(sudo whoami) echo "Was $NAME1, then became more powerful $NAME2" -# Read Bash shell builtins documentation with the bash 'help' builtin: +# Read Bash shell built-ins documentation with the bash `help` built-in: help help help help for @@ -450,12 +460,12 @@ help return help source help . -# Read Bash manpage documentation with man +# Read Bash manpage documentation with `man` apropos bash man 1 bash man bash -# Read info documentation with info (? for help) +# Read info documentation with `info` (`?` for help) apropos info | grep '^info.*(' man info info info diff --git a/perl6-pod.html.markdown b/perl6-pod.html.markdown new file mode 100644 index 00000000..6c769acb --- /dev/null +++ b/perl6-pod.html.markdown @@ -0,0 +1,619 @@ +--- +language: Pod +contributors: + - ["Luis F. Uceta", "https://uzluisf.gitlab.io/"] +filename: learnpod.pod6 +--- + +Perl 6 Pod is an easy-to-use and purely descriptive mark-up language, +with no presentational components. Besides its use for documenting +Perl 6 programs and modules, Pod can be utilized to write language +documentation, blogs, and other types of document composition as well. + +Pod documents can be easily converted to HTML and many other formats +(e.g., Markdown, Latex, plain text, etc.) by using the corresponding +variant of the `Pod::To` modules (e.g. `<Pod::To::HTML>` for HTML conversion). + +Note: This document can be also be found as a Pod document +[here](https://git.io/fpxKI). + +- [General Info](#general-info) +- [Pod Basics](#pod-basics) + - [Basic Text Formatting](#basic-text-formatting) + - [Headings](#headings) + - [Ordinary Paragraphs](#ordinary-paragraphs) + - [Lists](#lists) + - [Code Blocks](#code-blocks) + - [Comments](#comments) + - [Links](#links) + - [Tables](#tables) +- [Block Structures](#block-structures) + - [Abbreviated Blocks](#abbreviated-blocks) + - [Delimited Blocks](#delimited-blocks) + - [Paragraph Blocks](#paragraph-blocks) +- [Configuration Data](#configuration-data) + - [Standard Configuration Options](#standard-configuration-options) + - [Block Pre-configuration](#block-pre-configuration) +- [Semantic Blocks](#semantic-blocks) +- [Miscellaneous](#miscellaneous) + - [Notes](#notes) + - [Keyboard Input](#keyboard-input) + - [Terminal Output](#terminal-output) + - [Unicode](#unicode) +- [Rendering Pod](#rendering-pod) +- [Accessing Pod](#accessing-pod) + +## General Info + +Every Pod document has to begin with `=begin pod` and end with `=end pod`. +Everything between these two delimiters will be processed and used to +generate documentation. + +``` +=begin pod + +A very simple Perl 6 Pod document. All the other directives go here! + +=end pod +``` + +Pod documents usually coexist with Perl 6 code. If by themselves, Pod files +often have the `.pod6` suffix. Moving forward, it's assumed that the +constructs are between the `=begin pod ... =end pod` directives. + +## Pod Basics + +### Basic Text Formatting + +Text can be easily styled as bold, italic, underlined or verbatim (for code +formatting) using the formatting code: `B<>`, `I<>`, `U<>` and `C<>`. + +``` +B<This text is in Bold.> + +I<This text is in Italics.> + +U<This text is Underlined.> + +The function C<sub sum { $^x + $^y}> is treated as verbatim. +``` + +There are more formatting codes (e.g., `L<>`, `T<>`, etc.) but they'll be +discussed later throughout the document. You'll recognize them because they're +just a single capital letter followed immediately by a set of single or double +angle brackets. The Unicode variant («») can also be used. + +### Headings + +Headings are created by using the `=headN` directive where `N` is the +heading level. + +``` +=head1 This is level 1 +=head2 This is level 2 +=head3 This is level 3 +=head4 This is level 4 +=head5 This is level 5 +=head6 This is level 6 +``` + +### Ordinary Paragraphs + +Ordinary paragraphs consist of one or more adjacent lines of text, each of +which starts with a non-whitespace character. Any paragraph is terminated +by the first blank line or block directive. + +``` +=head1 First level heading block + +=head2 Paragraph 1 + +This is an ordinary paragraph. Its text will be squeezed and +short lines filled. It is terminated by the first blank line. + +=head2 Paragraph 2 + +This is another ordinary paragraph albeit shorter. +``` + +Alternatively, the `=para` directive can be used to explicitly mark adjacent +lines of text as a paragraph. + +``` +=head1 First level heading block + +=head2 Paragraph 1 + +=para +This is an ordinary paragraph. Its text will be squeezed and +short lines filled. It is terminated by the first blank line. + +=head2 Paragraph 2 + +=para +This is another ordinary paragraph albeit shorter. +``` + +### Lists + +Unordered lists can be made using the `=item` directive. + +``` +=item Item +=item Item +=item Another item +``` + +Sublists are achieved with items at each level specified using the `=item1`, +`=item2`, `=item3`, etc. directives. + +``` +=item1 Item one +=item1 Item two +=item1 Item three + =item2 Sub-item + =item2 Sub-item +=item1 Item four +``` + +Definition lists that define terms or commands use the `=defn`. This is +equivalent to the `<dl>` element in HTML. + +``` +=defn Beast of Bodmin +A large feline inhabiting Bodmin Moor. + +=defn Morgawr +A sea serpent. + +=defn Owlman +A giant owl-like creature. +``` + +### Code Blocks + +A code block is created (which uses the `<code>` element) by starting each +line with one or more whitespace characters. + +``` + #`( this is comment ) + my $sum = -> $x, $y { $x + $y } + say $sum(12, 5); +``` + +As shown in the [Basic Text Formatting](#basic-text-formatting) section, +inline code can be created using the `C<>` code. + +``` +In Perl 6, there are several functions/methods to output text. Some of them +are C<print>, C<put> and C<say>. +``` + +### Comments + +Although Pod blocks are ignored by the Perl 6 compiler, everything indentified +as a Pod block will be read and interpreted by Pod renderers. In order to +prevent Pod blocks from being rendered by any renderer, use the `=comment` +directive. + +``` +=comment Add more here about the algorithm. + +=comment Pod comments are great for documenting the documentation. +``` + +To create inline comments, use the `Z<>` code. + +``` +Pod is awesome Z<Of course it is!>. And Perl 6 too! +``` + +Given that the Perl interpreter never executes embedded Pod blocks, +comment blocks can also be used as an alternative form of nestable block +comments in Perl 6. + +### Links + +Creating links in Pod is quite easy and is done by enclosing them in +a `L<>` code. The general format is `L<Label|Url>` with `Label` +being optional. + +``` +Perl 6 homepage is L<https://perl6.org>. +L<Click me!|http://link.org/>. +``` + +Relative paths work too. + +``` +L<Go to music|/music/>. +``` + +Linking to a section in the same document works as well. + +``` +L<Link to Headings|#Headings> +``` + +### Tables + +The Pod 6 specifications are not completely handled properly yet and this +includes the handling of table. For simplicity's sake, only one way of +constructing tables is shown. To learn about good practices and see examples +of both good and bad tables, please visit +https://docs.perl6.org/language/tables. + +``` +=begin table +Option | Description +============|================ +data | path to data files. +engine | engine to be used for processing templates. +ext | extension to be used for dest files. +=end table +``` + +## Block Structures + +As mentioned earlier, Pod documents are specified using directives, which are +used to delimit blocks of textual content and declare optional [configuration +information](#configuration-data). Every directive starts with an equals +sign (`=`) in the first column. + +The content of a document is specified within one or more blocks. Every Pod +block may be declared in any of three equivalent forms: delimited style, +paragraph style, or abbreviated style. + +Up to this point, we only used the abbreviated style for the block +types (e.g., `=head1`, `=para`, `=comment`, `=item`, etc). + +### Abbreviated Blocks + +Abbreviated blocks are introduced by an `=` sign in the first column, which +is followed immediately by the `typename` of the block and then the content. +The rest of the line is treated as block data, rather than as configuration. +The content terminates at the next Pod directive or the first blank line +(which is not part of the block data). The general syntax is + +``` +=BLOCK_TYPE BLOCK_DATA +``` +For example: + +``` +=head1 Top level heading +``` + +### Delimited Blocks + +Delimited blocks are bounded by `=begin` and `=end` markers, both of which are +followed by a valid Perl 6 identifier, which is the `typename` of the block. +The general syntax is + +``` +=begin BLOCK_TYPE +BLOCK_DATA +=end BLOCK_TYPE +``` + +For example: + +``` +=begin head1 +Top level heading +=end head1 +``` + +This type of blocks is useful for creating headings, list items, code blocks, +etc. with multiple paragraphs. For example, + +* a multiline item of a list + +``` +=begin item +This is a paragraph in list item. + +This is another paragraph in the same list item. +=end item +``` + +* a code block + +``` +=begin code +#`(A recursive implementation of +a power function using multi subs. +) + +multi pow( Real $base, 0 ) { 1 } + +multi pow( Real $base, Int $exp where * >= 0) { + $base * pow($base, $exp - 1) +} + +multi pow( Real $base ) { + pow($base, 2) +} + +say pow(3, 0); #=> 1 +say pow(4.2, 2); #=> 17.64 +say pow(6); #=> 36 +=end code +``` + +### Paragraph Blocks + +Paragraph blocks are introduced by a `=for` marker and terminated by +the next Pod directive or the first blank line (which is not considered to +be part of the block's contents). The `=for` marker is followed by the +`typename` of the block. The general syntax is + +``` +=for BLOCK_TYPE +BLOCK DATA +``` + +For example: + +``` +=for head1 +Top level heading +``` + +## Configuration Data + +Except for abbreviated blocks, both delimited blocks and paragraph +blocks can be supplied with configuration information about their +contents right after the `typename` of the block. Thus the following +are more general syntaxes for these blocks: + +* Delimited blocks + +``` +=begin BLOCK_TYPE OPTIONAL_CONFIG_INFO += ADDITIONAL_CONFIG_INFO +BLOCK_DATA +=end BLOCK_TYPE +``` + +* Paragraph blocks + +``` +=for BLOCK_TYPE OPTIONAL_CONFIG_INFO += ADDITIONAL_CONFIG_INFO +BLOCK DATA +``` + +The configuration information is provided in a format akin to the +["colon pair"](https://docs.perl6.org/language/glossary#index-entry-Colon_Pair) +syntax in Perl 6. The following table is a simplified version of the +different ways in which configuration info can supplied. Please go to +https://docs.perl6.org/language/pod#Configuration_information for a more +thorough treatment of the subject. + +| Value | Specify with... | Example | +| :-------- | :------ | :------ | +| List | :key($elem1, $elem2, ...) | :tags('Pod', 'Perl6') | +| Hash | :key{$key1 => $value1, ...} | :feeds{url => 'perl6.org'} | +| Boolean | :key/:key(True) | :skip-test(True) | +| Boolean | :!key/:key(False) | :!skip-test | +| String | :key('string') | :nonexec-reason('SyntaxError') | +| Int | :key(2) | :post-number(6) | + + +### Standard Configuration Options + +Pod provides a small number of standard configuration options that can +be applied uniformly to built-in block types. Some of them are: + +* `:numbered` + +This option specifies that the block is to be numbered. The most common +use of this option is to create numbered headings and ordered lists, but it +can be applied to any block. + +For example: + +``` +=for head1 :numbered +The Problem +=for head1 :numbered +The Solution +=for head2 :numbered +Analysis +=for head3 :numbered +Overview +``` + +* `:allow` + +The value of the `:allow` option must be a list of the (single-letter) names +of one or more formatting codes. Those codes will then remain active inside +the code block. The option is most often used on `=code` blocks to allow +mark-up within those otherwise verbatim blocks, though it can be used in any +block that contains verbatim text. + +Given the following snippet: + +``` +=begin code :allow('B', 'I') +B<sub> greet( $name ) { + B<say> "Hello, $nameI<!>"; +} +=end code +``` + +we get the following output: + +<pre><strong>sub</strong> greet( $name ) { + <strong>say</strong> "Hello, $name<em>!</em>"; +} +</pre> + +This is highly dependent on the format output. For example, while this works +when Pod is converted to HTML, it might not work with Markdown. + +### Block Pre-configuration + +The `=config` directive allows you to prespecify standard configuration +information that is applied to every block of a particular type. +The general syntax for configuration directives is: + +``` +=config BLOCK_TYPE CONFIG OPTIONS += ADDITIONAL_CONFIG_INFO +``` + +For example, to specify that every heading level 1 be numbered, bold +and underlined, you preconfigure the `=head1` as follows: + +``` +=config head1 :formatted('B', 'U') :numbered +``` + +## Semantic Blocks + +All uppercase block typenames are reserved for specifying standard +documentation, publishing, source components, or meta-information. +Some of them are: + +``` +=NAME +=AUTHOR +=VERSION +=CREATED +=SYNOPSIS +=DESCRIPTION +=USAGE +``` + +Most of these blocks would typically be used in their full +delimited forms. For example, + +``` +=NAME B<Doc::Magic> + +=begin DESCRIPTION +This module helps you generate documentation automagically. +Not source code needed! Most of it is outsourced from a black hole. +=end DESCRIPTION + +=begin SYNOPSIS + use Doc::Magic; + + my Doc::Magic $doc .= new(); + + my $result = $doc.create-documentation($fh); +=end SYNOPSIS + +=AUTHOR Authorius Docus +=VERSION 42 +``` + +## Miscellaneous + +### Notes + +Notes are rendered as footnotes and created by enclosing a note in a +`N<>` code. + +``` +In addition, the language is also multi-paradigmatic N<According to Wikipedia, +this means that it supports procedural, object-oriented, and functional +programming.> +``` + +### Keyboard Input + +To flag text as keyboard input enclose it in a `K<>` code. + +``` +Enter your name K<John Doe> +``` + +### Terminal Output + +To flag text as terminal output enclose it in `T<>` code. + +``` +Hello, T<John Doe> +``` + +### Unicode + +To include Unicode code points or HTML5 character references in +a Pod document, enclose them in a `E<>` code. + +``` +Perl 6 makes considerable use of the E<171> and E<187> characters. +Perl 6 makes considerable use of the E<laquo> and E<raquo> characters. +``` + +this is rendered as: + +Perl 6 makes considerable use of the « and » characters. +Perl 6 makes considerable use of the « and » characters. + +## Rendering Pod + +To generate any output (i.e., Markdown, HTML, Text, etc.), you need to +have the Perl 6 compiler installed. In addition, you must install +a module (e.g., `Pod::To::Markdown`, `Pod::To::HTML`, `Pod::To::Text`, etc.) +that generates your desired output from Pod. + +For instructions about installing Perl 6, +[look here](https://perl6.org/downloads/). + +Run the following command to generate a certain output + +``` +perl6 --doc=TARGET input.pod6 > output.html +``` + +with `TARGET` being `Markdown`, `HTML`, `Text`, etc. Thus to generate +Markdown from Pod, run this: + +``` +perl6 --doc=Markdown input.pod6 > output.html +``` + +## Accessing Pod + +In order to access Pod documentation from within a Perl 6 program, +it is required to use the special `=` twigil (e.g., `$=pod`, `$=SYNOPSIS`,etc). + +The `=` twigil provides the introspection over the Pod structure, +providing a `Pod::Block` tree root from which it is possible to access +the whole structure of the Pod document. + +If we place the following piece of Perl 6 code and the Pod documentation +in the section [Semantic blocks](#semantic-blocks) in the same file: + +``` +my %used-directives; +for $=pod -> $pod-item { + for $pod-item.contents -> $pod-block { + next unless $pod-block ~~ Pod::Block::Named; + %used-directives{$pod-block.name} = True; + } +} + +say %used-directives.keys.join("\n"); +``` + +we get the following output: + +``` +SYNOPSIS +NAME +VERSION +AUTHOR +DESCRIPTION +``` + +## Additional Information + +* https://docs.perl6.org/language/pod +* https://docs.perl6.org/language/tables +* https://design.perl6.org/S26.html + |