From 2ddccd4072de9cd393576c3ea933d036cc34b22e Mon Sep 17 00:00:00 2001 From: gauthiier Date: Sat, 11 Dec 2021 15:50:05 +0100 Subject: [PATCH] new html / fixed template --- Lesson1.html | 60 +++++++++++------------ Lesson2.html | 111 +++++++++++++++++++++++++++---------------- Lesson3.html | 71 +++++++++++++-------------- Lesson4.html | 38 +++++++-------- Lesson5.html | 69 +++++++++------------------ index.html | 35 +++++--------- style/template.html5 | 3 -- 7 files changed, 180 insertions(+), 207 deletions(-) diff --git a/Lesson1.html b/Lesson1.html index 76cc829..7f11a42 100644 --- a/Lesson1.html +++ b/Lesson1.html @@ -4,7 +4,7 @@ - + Lesson1 -

CLI or the Command Line Interface

-

The Command Line Interface is the most common and pervasive interface directly linking fingers typing on a keyboard (text) and the computer (commands). The CLI is a legacy mode of operating computing system which can be traced back to early telegraphic devices. In this lesson we will look at your computer's own CLI and present ways in which you can use it to write, manipulate, analyse and transform text on your own computer system.

-
- -
+

CLI or the Command Line Interface

+

The Command Line Interface is the most common and pervasive interface directly linking fingers typing on a keyboard (text) and the computer (commands). The CLI is a legacy mode of operating computing system which can be traced back to early telegraphic devices. In this lesson we will look at your computer’s own CLI and present ways in which you can use it to write, manipulate, analyse and transform text on your own computer system.

+

Goals

The aim of this lesson is for readers to develop an appreciation of the advantages of using the CLI for certain types of work involving text editing on a computer. As the CLI itself is text based, our goal is to present the history of the CLI and discuss how text-based computer interfaces are still up to this day on of the most important ways to communicate with the computer systems.

-

The goals of this lesson are:

-
    +

    The goals of the lesson are:

    +
      +
    1. Understand the historical precedents leading to the development of modern CLI.
    2. Acquire basic knowledge on how to operate the CLI of your own computer.
      3. -
    3. Acquire just-enough CLI vocabulary to be used in future work.
      4. +
    4. Develop the ability to recognize where and when the CLI is a better alternative than other types of computer interfaces (mainly graphical).
      5. +
    5. Develop a critical perspective on why the CLI matters in some situation and when it does not.
      6. +
    6. Acquire just-enough basic CLI vocabulary to be used in future (research) work.
    +

    History

    +

    We can trace back the history of the text-based interface as mode operating computers to the telegraph and of course the typewriter. Years before computing (as we know it) was invented, the telegraph was already a ubiquitous telecommunication system. Early operators of the telegraph used hand-operated devices, the Morse key, to send Morse codes down the communication cable, an interface that had many limitations due to it’s rather crude operation mode. From the mid 19th century on, a few devices were invented that featured a multiple keys keyboard interface and related receiver apparatus that would print messages sent using the keyboard input device. These greatly improved the speed in which messages could be sent and received. However, messages printed using these devices were still encoded raw; a received message would usually be in punched holes format on a piece of paper tape. For this reason, trained operators capable of deciphering such codes were still key interpreters of the wired cables.

    +

    It is not until the beginning of the 20th century, with the advent of the Teletype (TTY), that sending and receiving tele-typed text over telegraph lines was fully automated. Quite similar to the typewriter, a TTY made reading and writing encoded text seamless: the teletypewriter would encode typed alphabetic characters and the teletypeprinter would decode received encoded characters in an alphabetic format. Hence sending a message to an endpoint would be as easy as typing on a normal typewriter. This new type of telecommunication interface greatly changed the face of news and print media as it enable reporters and writers to send and receive “cables” on their own (without the need to be trained operators themselves).

    +

    But why is the history of the TTY important for our concern here? Well there’s two major reasons. First, the Teletype was historically important for the development of text encoding (Lesson1). Early Teletype machines used the Baudot code encoding scheme but Teletype Model 33 (a standard TTY device in the 1960’s and 1970’s) used the ASCII encoding scheme. For this reason, ASCII (and modern UTF-8) has, still to this days, control codes that refer to networking operational commands. These characters attest the legacy of TTY devices. Second, as a result of ASCII integration in Model 33, the TTY became an central interface to mainframe computing machinery in the 1960’s and 1970’s. Before the advent of the TTY, the standard computing interface was the punch card format. TTY introduced direct input of computing commands from the teletypewriter and formalised the output as teleprinted on paper (ASCII also have printing control codes). For a long period of time, the main medium of computing was printed paper.1

    +

    A quick note here to emphasize the fact that computing was done on mainframes back in these days. The “mainframe” was a “colossus” computer residing somewhere in a local or remote building. As explained above, interfacing with the mainframe was done on a TTY device. This type of topology lead to the term “terminal” to signify a user’s endpoint (where the fingers and the eyes are) and “time-sharing” to signify that the mainframe shared its computing time between multiple users and their respective terminals. Much like the early TTY/telegraph coupling, a user would send computing commands on his TTY device over a network cable and receive the results back from the mainframe onto the same device. Rather than “discuss” with another fellow human over the network, you would now “discuss” with the shared computer.

    +
    +Datapoint3300 +
    +

    The first terminal to showcase a screen as output device (rather than paper) was the Datapoint 3300 by Computer Terminal Corporation (CTC).2 Other than having a glassy CTR screen, the main feature of the Datapoint 3300 was that it could seamlessly replace the Teletype Model 33 terminal and perform paperless the same operations. However, the Datapoint 3300 had obviously different circuitry than the Model 33. In order to drive its CTR monitor, CTC devised special electronic circuitry that kept track of the characters displayed on screen (shift-registers - a type of operational memory). The story goes that CTC, having a need to upgrade its circuitry, asked Intel and Texas Instrument (which are integrated circuit manufacturer) to produce a special ship that would be used to program its future screen-based terminals.3 This challenge lead to the development of one Intel’s first 8-bit microprocessor - the Intel 8008.4

    +

    The direct descendant of the Datapoint 3300, the Datapoint 2200 was the first programmable terminal, viewed by many as the first personal computer. The fact that the Datapoint 2200 was programmable, meaning that code could be written for and ran on the terminal’s circuit itself and not on a mainframe made it very attractive to computer programmers. Commands could be issued on the Command Line Interface and directly resolved locally without the need of an (expensive) mainframe.

    +

    This is were the story of terminals ends. If code is executed locally and not remotely, it is erroneous to talk about a terminal porperly saying but instead once must talk about the CLI (i.e., no more remote terminal but he emulation of the mainframe, as for the Datapoint 2200).

    How

    -

    To access to the Command Line Interface of your computer you need a Command Line Interpreter. Every mdoern Operating System (OS) have such interpreter built-in. In fact, the Command Line Interpreter are legacy systems on most OS (OSX, Windows, Linux, Unix, etc.) because there was a time when interfacing with a computer was solely done typing commands on a terminal.1 Most computer programmers, even nowadays, use the computer CLI on a daily basis to write and run software and even to debug hardware.

    +

    To access to the Command Line Interface of your computer you need a Command Line Interpreter. Every mdoern Operating System (OS) have such interpreter built-in. In fact, the Command Line Interpreter are legacy systems on most OS (OSX, Windows, Linux, Unix, etc.) because there was a time when interfacing with a computer was solely done typing commands on a terminal.5 Most computer programmers, even nowadays, use the computer CLI on a daily basis to write and run software and even to debug hardware.

    Depending on which OS you are using, accessing its CLI is quite simple:

      -

    • On OSX, the "Terminal" application resides in the "Utilities" folder under "Applications".

      • -

    • On Windows, you access the CMD.EXE command prompt by typing "cmd" in the search bar of the "Start" menu

      • +

    • On OSX, the “Terminal” application resides in the “Utilities” folder under “Applications”.

      • +

    • On Windows, you access the CMD.EXE command prompt by typing “cmd” in the search bar of the “Start” menu

    On OSX your CLI should look like:

    -
    - -
    -

    Bingo! Say hello to the computer's CLI!

    +

    +

    Bingo! Say hello to the computer’s CLI!

    Now in order to utilise the CLI in a productive way you need to learn a couple of fundamental commands.

    -
      -

    1. "ls" (OSX, Linux, Unix) and "dir" (Windows): lists all files and folders inside the directory your CLI's current working directory.

      2. -

    2. "cd": changes the CLI's current working directory

      3. +
        +

      1. “ls” (OSX, Linux, Unix) and “dir” (Windows): lists all files and folders inside the directory your CLI’s current working directory.

        2. +

      2. “cd”: changes the CLI’s current working directory

      -

      Using both commands, you can basically navigate your whole filesystem. It is important at this point to understand the idea of a "working directory" as commands issued on the CLI usually depends in the files present in its "working directory".

      -

      We are now going to illustrate some useful commands (under OSX) that deal with text files and the likes. Hence, we will point our "shell" (another common name for the CLI) to the folder containing the files of this site.

      -

      Issuing the "ls" command results in:

      +

      Using both commands, you can basically navigate your whole filesystem. It is important at this point to understand the idea of a “working directory” as commands issued on the CLI usually depends in the files present in its “working directory”.

      +

      We are now going to illustrate some useful commands (under OSX) that deal with text files and the likes. Hence, we will point our “shell” (another common name for the CLI) to the folder containing the files of this site.

      +

      Issuing the “ls” command results in:

      Gauthiier:wwwriting gauthiier$ ls
 Lesson1.html  Lesson2.md    Lesson5.md    index.html    wwwrite.bib
 Lesson1.md    Lesson3.md    Lesson6.md    index.md
 Lesson2.html  Lesson4.md    img/          style/
      -

      As you can see, directories are denoted with a leading "/" while files are not. Hence, "img/" is a directory and "Lesson1.md" is a file.

      -

      It is possible to list the content of directories using "ls" without changing the "working directory". For example, let's list the content of the directory "style/":

      +

      As you can see, directories are denoted with a leading “/” while files are not. Hence, “img/” is a directory and “Lesson1.md” is a file.

      +

      It is possible to list the content of directories using “ls” without changing the “working directory”. For example, let’s list the content of the directory “style/”:

      Gauthiier:wwwriting gauthiier$ ls style/
 style.css       template.html5
      -

      Ok now let's play with file (meta)data.

      -

      The command "file" can tell you what type a file is. For example:

      +

      Ok now let’s play with file (meta)data.

      +

      The command “file” can tell you what type a file is. For example:

      Gauthiier:wwwriting gauthiier$ file wwwrite.bib 
 wwwrite.bib: UTF-8 Unicode English text, with very long lines
      -

      The command "wc" (word count) returns information about the content of the file:

      +

      The command “wc” (word count) returns information about the content of the file:

      Gauthiier:wwwriting gauthiier$ wc Lesson1.md
  118    1995   13100 Lesson1.md

      where (1) the first column indicates the number of lines, (2) the second column the number of words and (3) the third column the number of bytes.

      -

      The command "grep" matches words to files that contain them (search). "grep" can search a specific file or lookup files recursively in a directory.

      -

      Let's look up the word: wwword.

      +

      The command “grep” matches words to files that contain them (search). “grep” can search a specific file or lookup files recursively in a directory.

      +

      Let’s look up the word: wwword.

      Gauthiier:wwwriting gauthiier$ grep "wwword" Lesson2.md
 Let's look up the word: wwword.
      -

      "grep" gives the exact line-text where the word in found in the file.

      +

      “grep” gives the exact line-text where the word in found in the file.

      Similarly we can look up the number of times a word appears in each files ending with .md or .html in the current working directory:

      Gauthiier:wwwriting gauthiier$ grep -rc --include=*.{md,html} "wwword" .
 ./index.html:0
@@ -78,21 +85,43 @@ Let's look up the word: wwword.
      ./Lesson4.md:0 ./Lesson5.md:0 ./Lesson6.md:0 -

      As you can see the command "grep" can be instructed, using certain command parameters, to perform quite advanced searches. In general all commands from the CLI have specific parameters that can be set to specify a specific ways in which to conduct their operations.

      +

      As you can see the command “grep” can be instructed, using certain command parameters, to perform quite advanced searches. In general all commands from the CLI have specific parameters that can be set to specify a specific ways in which to conduct their operations.

      It is, of course, out of the scope of this lesson to present all possible commands one can use to manipulate files and directories. For the remaining lessons, you only have to remember how to point your CLI to a specific working directory.

      Extra

      -

      OSX Unix Tutorial for Beginners

      +

      Unix Tutorial for Beginners

      A beginners guide to the Command Prompt (Windows)

      -

      A list of all commands: OSX - Windows

      -
      +

      A list of all commands: OSX Windows Linux (bash)

      +

      References

      + + + +
        -

      1. Something that is easily forgotten in the era of ubiquitous computer Graphical User Interface (GUI). The CLI is to some degree reminescent of the Teletype (TTY).↩

        2. +

      2. Something that is easily forgotten in the era of ubiquitous computer screens. For a discussion on the topic see Nick Montfort’s essay Continuous Paper: The Early Materiality and Workings of Electronic Literature.↩︎

        3. +

      3. Datapoint 3300 brochure.↩︎

        4. +

      4. In fact Victor Poor from CTC devised the architecture and instruction set. The instruction set is, to this day, found (a revised version of course) on Intel’s flagship x86 architecture, the most pervasive microprocessor architecture of all time (typing this text was processed by a x86 microprocessor).↩︎

        5. +

      5. And subsequently the legacy 8-bit Intel 8080, 16-bit Intel 8086 and the whole x86 family of microprocessors. For all the details of the development of the Intel 8008, please refer to this document.↩︎

        6. +

      6. Something that is easily forgotten in the era of ubiquitous computer Graphical User Interface (GUI). The CLI is to some degree reminescent of the Teletype (TTY).↩︎

      -
      + diff --git a/Lesson3.html b/Lesson3.html index f21b952..87f3f57 100644 --- a/Lesson3.html +++ b/Lesson3.html @@ -4,37 +4,35 @@ - + Lesson3 -

      Markup / Markdown

      -

      Markup languages are one of the most pervasive and common types of language on the Internet. In fact HTML is a type of markup language responsible to instruct our web browsers on how to layout text, images and the likes on our screens. Behind all web pages, there is a markup text file that is sent from a server to our browsers when we type in a URL. The beauty of markup languages is that they are both human-readable and machine-readable and written in plain text format. Reading a marked up text one can notice the special "meta-codes" and related syntax that direct machines in interpreting the same text. The idea is thus to have some standards and conventions describing these meta-codes and expected machine interpretation.

      +

      Markup languages are one of the most pervasive and common types of language on the Internet. In fact HTML is a type of markup language responsible to instruct our web browsers on how to layout text, images and the likes on our screens. Behind all web pages, there is a markup text file that is sent from a server to our browsers when we type in a URL. The beauty of markup languages is that they are both human-readable and machine-readable and written in plain text format. Reading a marked up text one can notice the special “meta-codes” and related syntax that direct machines in interpreting the same text. The idea is thus to have some standards and conventions describing these meta-codes and expected machine interpretation.

      Goals

      In this lesson we will introduce the Markdown language for writing (academic) texts. Markdown is a type of markup language that features very intuitive set of meta-codes and a simple syntax that can seamlessly integrate with normal text without transforming them much.

      The aims of this lesson are:

      -
        -
      1. Understand the basic syntax of Markdown and be able to write markdown valid text.
        2. +
          +
        1. Understand the basic syntax of Markdown and be able to write markdown valid text.
          +
        2. Acquire just-enough Markdown vocabulary to be used in future work.

        How

        Before we delve into the Markdown language, it is important to understand why we use it. A file written in the language has the benefit of being interpreted and hence converted into various types of output formats. Depending on the type markdown interpreter / converter, documents formats such as HTML, PDF, EPUB, DOC, etc. can be produced out of a single markdown file source. This is the main reason the language is widely used; to easily generate web pages, pdf publications and epub without having to directly code their actual inner formats. In using markdown as a source language, all of the above formats are made available for you to publish in. How to convert markdown file is discussed in the next lesson.

        -

        The premise of this lesson is going to be very simple. Since this lesson is written in Markdown, snippets the language/syntax will be discussed and exemplified in-line in HTML format.1

        +

        The premise of this lesson is going to be very simple. Since this lesson is written in Markdown, snippets the language/syntax will be discussed and exemplified in-line in HTML format.1

        italic and bold

        -

        Let's start with the simplest: italic and bold

        +

        Let’s start with the simplest: italic and bold

        Let's start with the simplest: _italic_ and __bold__
        -

        Notice the single (italic) and double (bold) underscores '_'?

        -

        Let's continue with the same: italic and bold

        +

        Notice the single (italic) and double (bold) underscores ’_’?

        +

        Let’s continue with the same: italic and bold

        Let's continue with the same: *italic* and **bold**
        -

        Notice the single (italic) and double (bold) stars '*'?

        +

        Notice the single (italic) and double (bold) stars ’*’?

        Headers & TOC Sections

        -

        Now since we are writing text, let's now look at how Markdown detonates headers.

        -

        Using the hash mark '#' one can generate various types of headers by prefixing a "title" with a concatenation of hash marks '#'.

        +

        Now since we are writing text, let’s now look at how Markdown detonates headers.

        +

        Using the hash mark ‘#’ one can generate various types of headers by prefixing a “title” with a concatenation of hash marks ‘#’.

        Title: Un

        Title: Deux

        Title: Trois

        @@ -51,16 +49,16 @@

        (Block) Quotes

        Blockquotes are also very simple.

        -

        "Mais la seule question quand on écrit, c'est de savoir avec quelle autre machine la machine littéraire peut être brancheé, et doit être branchée pour fonctionner."

        +

        “Mais la seule question quand on écrit, c’est de savoir avec quelle autre machine la machine littéraire peut être brancheé, et doit être branchée pour fonctionner.”

        -

        -- Deleuze & Guattari, Milles Plateaux

        +

        – Deleuze & Guattari, Milles Plateaux

        > "Mais la seule question quand on écrit, c'est de savoir avec quelle autre machine la machine littéraire peut être brancheé, et doit être branchée pour fonctionner." 
 
 -- Deleuze & Guattari, _Milles Plateaux_

        Lists

        There is a few valid syntax for lists.

        Below are two common ones:

        -
          +
          1. List 1 item 1
          2. List 1 item 2
          3. List 1 item 3
            4. @@ -71,7 +69,6 @@ 3. List 1 item 3 4. List 1 item 4 -
            • List 2 item 1
            • List 2 item 2
              • @@ -83,7 +80,6 @@ - List 2 item 3 - List 2 item 4 -

              Nested lists:

              • List 3 item 1 @@ -110,7 +106,6 @@ - List 3 item 2.1.1 - List 3 item 2.1.1.1 -

                Now the interesting stuff. (Hyper)-Linking is one of the salient feature of digital documents. Hence markdown makes it very easy to write links to a URL.

                this is a link to Lesson2 with an absolute URL

                @@ -121,20 +116,20 @@

                Images

                Inserting images into the document is done in a similar fashion, linking the image using the same syntax as above.

                For example - absolute URL

                -
                -Jules Henri Poincaré

                Jules Henri Poincaré

                -
                +
                +Jules Henri Poincaré +
                ![Jules Henri Poincaré](http://gauthiier.info/+++/jules-henri.png)

                and - relative URL

                -
                -Jules Henri Poincaré

                Jules Henri Poincaré

                -
                +
                +Jules Henri Poincaré +
                ![Jules Henri Poincaré](img/jules-henri.png)
                -

                As you can see, the bang character '!' is the only add-on to link syntax while the caption of the image replaces the text on the link.

                +

                As you can see, the bang character ‘!’ is the only add-on to link syntax while the caption of the image replaces the text on the link.

                Footnotes

                When one has something to write that does not directly relate the core argument of a paragraph but nonetheless relates to its context, footnotes are a very practical way to branch of topic while keeping the reader not far from getting back into the main flow.

                The markdown syntax of a footnotes is as follow:

                -

                I think you are eager to start writing markdown2.

                +

                I think you are eager to start writing markdown2.

                I think you are eager to start writing markdown[^2].

                And further down in the document

                [^2]: And I hope you will do so very soon!
                @@ -145,23 +140,21 @@ 
                ---

                Such delimiters are useful when one wants to graphically separate parts of a text.

                -

                We have now covered the most basic syntactic elements of the markdown language. In most cases these are enough to write great texts and even write entire books. All of the above syntax is suited for the content of texts, however you are yet to introduce how to layout and style the output of a markdown text file.

                -

                The idea of behind markup languages is to create a clear division between content and style. Here we have covered the content side . Document conversion is covered in Lesson 4 while Lesson 6 introduces how styling can be applied to the output of such conversion.

                +

                We have now covered the most basic syntactic elements of the markdown language. In most cases, these are enough to write great texts and even write entire books. All of the above syntax is suited for the content of texts, however, we are yet to introduce how to layout and style the output of a markdown input file. The idea of behind markup languages is to create a clear division between content and style. Here we have covered the content side . Document conversion is covered in Lesson 4 while Lesson 6 introduces how styling can be applied to the output of such conversion.

                Extra

                +

                Online markdown editor

                Pandoc markdown primer

                -

                A thorough list of all markdown syntax

                +

                A thorough list of all pandoc style markdown syntax

                A very handy functionality of Sublime Text is its syntax highlighting for markdown. To enable such feature:

                -

                Menu --> Syntax --> Markdown --> Markdown

                -
                - -
                -
                +

                Menu –> Syntax –> Markdown –> Markdown

                +

                References

                +
                  -

                1. Not to mention that you can directly open and read this file "Lesson3.md" and see how it is written.↩

                  2. -

                2. And I hope you will do so very soon!↩

                  3. +

                3. Not to mention that you can directly open and read this file “Lesson3.md” and see how it is written.↩︎

                  4. +

                4. And I hope you will do so very soon!↩︎

                -
                + diff --git a/Lesson4.html b/Lesson4.html index 4a0e757..415c4a3 100644 --- a/Lesson4.html +++ b/Lesson4.html @@ -4,11 +4,8 @@ - + Lesson4 - @@ -18,13 +15,13 @@

                Goals

                Assuming that you have a basic knowledge of the Markdown language, in this lesson you will learn how to convert a text file written in markdown to both an HTML and EPUB3 output. In order to do so, you need to instal Pandoc on your system as we will be using this specific markdown converter.

                The goals of this lesson are:

                -
                  +
                  1. Acquire basic understanding of how to employ pandoc to produce both HTML and EPUB output.
                  2. Acquire basic knowledge of how pandoc can be tailored to produce other types of output.

                  How

                  -

                  In order to complete this lesson, you should be familiar with how to operated your computer's CLI (Lesson2) and capable of writing markdown valid text (Lesson3).

                  -

                  The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don't already, simply use this file (Lesson4.md).

                  +

                  In order to complete this lesson, you should be familiar with how to operated your computer’s CLI (Lesson2) and capable of writing markdown valid text (Lesson3).

                  +

                  The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don’t already, simply use this file (Lesson4.md).

                  To make sure that your system is set up properly, open a CLI window and type the following

                  pandoc --version

                  If you get an error message, this means that you did not install pandoc properly. If so please visit Pandoc and install the required software. If not you are ready to go!

                  @@ -34,8 +31,8 @@

                  will produce an output file (-o Lesson4.html) from the input file (Lesson4.md). Here the argument -s will force pandoc to produce an entire valid document rather than a snippet of it.

                  More formally, the former command could be

                  pandoc -s -f markdown Lesson4.md -t html5 -o Lesson4.html
                  -

                  meaning the input file (Lesson4.md) is of type "markdown" and the output file (-o Lesson4.html) is of type "html5". You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.

                  -

                  Now let's simply change the output to the Rich Text Format (rtf)

                  +

                  meaning the input file (Lesson4.md) is of type “markdown” and the output file (-o Lesson4.html) is of type “html5”. You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.

                  +

                  Now let’s simply change the output to the Rich Text Format (rtf)

                  pandoc -s -f markdown Lesson4.md -t rtf -o Lesson4.rtf

                  or in a more compact version

                  pandoc -s Lesson4.md -o Lesson4.rtf
                  @@ -54,20 +51,20 @@ 
                  pandoc -s Lesson4.md --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib -o Lesson4.html

                  Now refresh your web browser and see if something changed. Perhaps not (yet). You may not realise it but you have (re)generated the entire HTML in a single pandoc command!

                  As you can see there is a little more arguments in the above pandoc than previously exposed in the first section.

                  -
                    +

                    1. As expected we have

                      -
                      -s Lesson4.md  -o Lesson4.html
                      +
                       -s Lesson4.md  -o Lesson4.html

                      which specifies the markdown input (Lesson4.md) and HTML output (Lesson4.html)

                    2. There is a few extra options

                      -
                      --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib
                      -

                      which are instructing pandoc to (1) use the HTML5 template "style/template.html5", (2) use the stylesheet "style/html5.css" and (3) use the bibliographical information in "wwwrite.bib" if in-text referencing is needed.

                      3. +
                       --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib
                      +

                      which are instructing pandoc to (1) use the HTML5 template “style/template.html5”, (2) use the stylesheet “style/html5.css” and (3) use the bibliographical information in “wwwrite.bib” if in-text referencing is needed.

                    -

                    Without going in too much details (since this is the topic of Lesson6), the current site employs custom templates and stylesheets (in the directory "style/"). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and CSS formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc's median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.

                    +

                    Without going in too much details (since this is the topic of Lesson6), the current site employs custom templates and stylesheets (in the directory “style/”). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and CSS formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc’s median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.

                    EPUB(3)

                    -

                    It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language "markdown" to another markup language "HTML5". At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.

                    +

                    It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language “markdown” to another markup language “HTML5”. At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.

                    Now here is the pandoc command to generate an epub(3) of the whole site

                    pandoc -S index.md Lesson1.md Lesson2.md Lesson3.md metadata.epub3.yaml  --toc --template=style/template.epub3 --epub-stylesheet=style/epub3.css --epub-cover-image=img/DSP6.png --bibliography=wwwrite.bib -o WWWRITE.epub
                    -

                    As you may notice, the command is a bit more "complex" than the previous HTML one, yet basically resembles it in many ways.

                    +

                    As you may notice, the command is a bit more “complex” than the previous HTML one, yet basically resembles it in many ways.

                    The arguments

                    -S index.md Lesson1.md Lesson2.md Lesson3.md Lesson4.md metadata.epub3.yaml -o WWWRITE.epub

                    specify a list of input files (index.md, Lesson1.md, Lesson2.md, Lesson3.md, Lesson4.md, and metadata.epub3.yaml) and an output file (-o WWWRITE.epub). Pandoc will concatenate input files into a single one when listed as inputs. This is convenient as it enables a writer to segment a book into self-contained chapters for example.

                    @@ -79,15 +76,12 @@

                    which tells pandoc to use the specified image as cover page for the EPUB.

                    Finally the argument

                    --toc
                    -

                    is a feature that instructs pandoc to generate a "Table Of Content" (toc) out of the various markdown Headings (symbol '#' Lesson3) present in the input file(s).

                    -

                    Let's now have a look at the EPUB output!

                    +

                    is a feature that instructs pandoc to generate a “Table Of Content” (toc) out of the various markdown Headings (symbol ‘#’ Lesson3) present in the input file(s).

                    +

                    Let’s now have a look at the EPUB output!

                    Extra

                    Try pandoc!

                    -

                    Pandoc User's Guide

                    +

                    Pandoc User’s Guide

                    Getting Started

                    -
                    - -
                    diff --git a/Lesson5.html b/Lesson5.html index 6309112..5d54e00 100644 --- a/Lesson5.html +++ b/Lesson5.html @@ -4,11 +4,8 @@ - + Lesson5 - @@ -16,9 +13,9 @@

                    Bibliographer

                    Compiling and producing a bibliography is an central part in writing academic texts. One can derive an overview of a text solely by glimpsing its bibliography. Being able to reference work in a standard fashion is usually required for most publications. However, the practice of manually writing a bibliography may at times be quite laborious. Because bibliographic standards (citation styles) vary depending on disciplines, and because various formats can change depending on the type of work that is referenced, it is easy to make mistakes and omit to include information here and there. Yet since bibliographic citation styles each have clear rules, it is rather trivial to implement bibliographic reading and writing systems using computers. Such systems certainly exists and are used to (1) gather bibliographic information into a database and (2) to output information in text format following whichever bibliographic standard it is instructed to – in short, they are capable of reading and writing such peculiar type of text.

                    Goals

                    -

                    This lessons introduces how to use software to produce bibliographies for texts written in markdown and using pandoc as document converter. Zotero is the program which will be demonstrated, yet other programs having the functionality of producing BibTeX formatted files (.bib) may also be used in conjunction with pandoc.1

                    +

                    This lessons introduces how to use software to produce bibliographies for texts written in markdown and using pandoc as document converter. Zotero is the program which will be demonstrated, yet other programs having the functionality of producing BibTeX formatted files (.bib) may also be used in conjunction with pandoc.1

                    In short, the objectives of this lesson are:

                    -
                      +
                      1. Acquire basic understanding on how to use Zotero in gathering bibliographical information.
                      2. Acquire basic understanding on how to use Zotero to manage research references.
                      3. Learn how to compile and export a BibTeX bibliography (and possibly other formats) using Zotero.
                        4. @@ -26,29 +23,19 @@

                      To install Zotero, please follow this link and install the Standalone version and related browser extension.

                      How

                      -
                      - -
                      -

                      Zotero brands itself as a "research organiser", meaning that it can collect and arrange academic research information under a simple interface. As you can see from the above image, in a nutshell, Zotero is a list of works (books, blog posts, chapters, journal articles, etc.) augmented with meta-data (notes, tags, relations, etc.). Each work has, of course, a formal description adequate to the type of work it represents. For example, a blog post has an URL while a journal article may have a volume identifier. The goal here is not to delve into the details of each formats relating to each types of work that can be represented in Zotero, but rather to make use of it and see how it proceeds in formalising types of work.

                      +

                      +

                      Zotero brands itself as a “research organiser”, meaning that it can collect and arrange academic research information under a simple interface. As you can see from the above image, in a nutshell, Zotero is a list of works (books, blog posts, chapters, journal articles, etc.) augmented with meta-data (notes, tags, relations, etc.). Each work has, of course, a formal description adequate to the type of work it represents. For example, a blog post has an URL while a journal article may have a volume identifier. The goal here is not to delve into the details of each formats relating to each types of work that can be represented in Zotero, but rather to make use of it and see how it proceeds in formalising types of work.

                      If it is the first time you ever used Zotero, your works list should be empty. Here are two common ways to populate your database:

                      1. Add an Item by Identifier

                      -
                      - -
                      -

                      Identifiers such as ISBN and DOI can be utilised to add items to Zotero using the special "add" button on the top menu bar. Each of ISBN and DOI are unique identifiers that refer to a specific work. Such identifiers are common and can be found on websites as as Amazon or a library website or simply directly printed in a book.

                      +

                      +

                      Identifiers such as ISBN and DOI can be utilised to add items to Zotero using the special “add” button on the top menu bar. Each of ISBN and DOI are unique identifiers that refer to a specific work. Such identifiers are common and can be found on websites as as Amazon or a library website or simply directly printed in a book.

                      2. Add an Item with browser extension

                      -
                      - -
                      -

                      When you installed the standalone version of Zotero, an extension (plug-in) for your web browser was also available to install. Using this plug-in on your browser helps you collect bibliographical items on the web. Depending on your type of browser (Safari, Chrome, Firefox) you should see a small Zotero icon near your address bar. When an web page presents an bibliographical item that can be added to Zotero, the icon will change aspect (or literately appear) signifying that when clicked, the item will automatically be inserted in Zotero's database. This comes very handy when browsing journals' websites for example. Adding an article to Zotero becomes very easy (as exemplified in the image above).

                      +

                      +

                      When you installed the standalone version of Zotero, an extension (plug-in) for your web browser was also available to install. Using this plug-in on your browser helps you collect bibliographical items on the web. Depending on your type of browser (Safari, Chrome, Firefox) you should see a small Zotero icon near your address bar. When an web page presents an bibliographical item that can be added to Zotero, the icon will change aspect (or literately appear) signifying that when clicked, the item will automatically be inserted in Zotero’s database. This comes very handy when browsing journals’ websites for example. Adding an article to Zotero becomes very easy (as exemplified in the image above).

                      You should now be able to populate your Zotero database in a click.

                      -
                      - -
                      -

                      Compiling a bibliography and / or exporting Zotero items it is as easy. Zotero let's you select individual items that can be exported in various formats (such as BibTeX) or even compiled into a formatted bibliography.

                      -
                      - -
                      +

                      +

                      Compiling a bibliography and / or exporting Zotero items it is as easy. Zotero let’s you select individual items that can be exported in various formats (such as BibTeX) or even compiled into a formatted bibliography.

                      +

                      For the purpose of this lesson, exporting selected Zotero items in the BibTeX format allows for referencing work from a markdown text using pandoc. This should produce a .bib file with all the information needed to produce a bibliography. The content of the file should look like the following.

                      @book{lazzarato_signs_2014,
     address = {Los Angeles, CA},
@@ -111,43 +98,33 @@
     year = {1995},
     pages = {96}
 }
                      -

                      The BibTeX is yet another text-based human-readable format that accounts for all information needed in producing a proper bibliography. As you can see, the information is a kind of median representation of works, meaning that it is not yet formatted according to particular standard citation style2. Instead it arranges and orders each work's information in a standard structure with tags that can easily be parsed by a citation processor such as the one included in pandoc.

                      +

                      The BibTeX is yet another text-based human-readable format that accounts for all information needed in producing a proper bibliography. As you can see, the information is a kind of median representation of works, meaning that it is not yet formatted according to particular standard citation style2. Instead it arranges and orders each work’s information in a standard structure with tags that can easily be parsed by a citation processor such as the one included in pandoc.

                      Citing with pandoc is straight forward.

                      -

                      Pandoc must first be instructed to link the generated .bib file with the specific markdown input file when creating an output document. This is done with a single parameter on the CLI. For example, the above BibTeX has been added to this site's wwwrite.bib and used to generated this page usign the following command:

                      +

                      Pandoc must first be instructed to link the generated .bib file with the specific markdown input file when creating an output document. This is done with a single parameter on the CLI. For example, the above BibTeX has been added to this site’s wwwrite.bib and used to generated this page usign the following command:

                      pandoc -s Lesson5.md --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib -o Lesson5.html

                      The important argument here being

                      --bibliography=wwwrite.bib
                      -

                      Now let's cite a source from the BibTeX.

                      -

                      For example, let's cite the work of Guattari who says "Since then, I have tried to nurture this machinic object, although I admit it is not something I control, rather it is a kind of core to which I am repeatedly led back."(Guattari 1995)

                      +

                      Now let’s cite a source from the BibTeX.

                      +

                      For example, let’s cite the work of Guattari who says “Since then, I have tried to nurture this machinic object, although I admit it is not something I control, rather it is a kind of core to which I am repeatedly led back.”[@guattari_machines_1995]

                      In markdown, the citation is written:

                      "Since then, I have tried to nurture this machinic object, although I admit it is not something I control, rather it is a kind of core to which I am repeatedly led back."[@guattari_machines_1995]
                      -

                      Easy. To reference a work "in-text", one only has to specify an item's entry identifier form the .bib file (here "guattari_machines_1995") and prefix it with a '@' symbol and bracketed with both opening '[' and closing ']'. Not only pandoc will "signposts" the citation in-text (at the specific text location) but also formats and appends the citation's reference at the end of the output file (see the References section of this document).

                      -

                      You can also reference multiple authors such as the ones listed above (Lazzarato 2014; Kirschenbaum 2012; Hansen 2012; Guattari 2009) and look up their referenced works below.

                      +

                      Easy. To reference a work “in-text”, one only has to specify an item’s entry identifier form the .bib file (here “guattari_machines_1995”) and prefix it with a ‘@’ symbol and bracketed with both opening ‘[’ and closing ’]’. Not only pandoc will “signposts” the citation in-text (at the specific text location) but also formats and appends the citation’s reference at the end of the output file (see the References section of this document).

                      +

                      You can also reference multiple authors such as the ones listed above [@lazzarato_signs_2014; @kirschenbaum_mechanisms_2012; @hansen_technics_2012; @guattari_soft_2009] and look up their referenced works below.

                      [@lazzarato_signs_2014; @kirschenbaum_mechanisms_2012; @hansen_technics_2012; @guattari_soft_2009]

                      Extra

                      Zotero Documentation

                      -

                      Citation Section of Pandoc's User Guide

                      +

                      Citation Section of Pandoc’s User Guide

                      References

                      - - - -
                      -

                      Guattari, Félix. 1995. “On Machines.” Edited by Andrew Benjamin. Complexity: architecture, Art, Philosophy, Journal of Philosophy and the Visual Arts, no. 6: 96.

                      -

                      ———. 2009. Soft Subversions: texts and Interviews 1977-1985. Semiotext(E) Foreign Agents Series. Los Angeles : Cambridge, Mass: Semiotext(e) ; Distributed by the MIT Press.

                      -

                      Hansen, Mark B. N. 2012. “Technics Beyond the Temporal Object.” New Formations 77 (1): 44–62. doi:10.3898/NEWF.77.03.2012.

                      -

                      Kirschenbaum, Matthew G. 2012. Mechanisms: new Media and the Forensic Imagination. Cambridge, Mass.; London: MIT Press.

                      -

                      Lazzarato, M. 2014. Signs and Machines: capitalism and the Production of Subjectivity. Semiotext(E) Foreign Agents Series. Los Angeles, CA: Semiotext(e).

                      -
                      -
                      +
                        -

                      1. Mendeley, EndNote, RefWorks, etc. - Zotero is presented because it is an open source project developed by the academic community.↩

                        2. -

                      2. There is many citation styles used in various disciplines. For a list of styles according to their disciplines, please refer to this guide.↩

                        3. +

                      3. Mendeley, EndNote, RefWorks, etc. - Zotero is presented because it is an open source project developed by the academic community.↩︎

                        4. +

                      4. There is many citation styles used in various disciplines. For a list of styles according to their disciplines, please refer to this guide.↩︎

                      -
                      + diff --git a/index.html b/index.html index ebaf7f9..049785f 100644 --- a/index.html +++ b/index.html @@ -6,9 +6,6 @@ WWWRITING WITH WIT - @@ -20,18 +17,18 @@

                      Intent

                      -

                      This site is intended to introduce humanities research writers how to write text in a modern fashion using their computers. The aim of the lessons listed below are points of departure for the practice of writing text using simple, basic yet advance systems and technologies. Part of this endeavour is first and foremost to empower writers to use these systems in presenting simple didactic material working towards bootstrapping their understanding of writing technologies and help them develop a new type of literacy (albeit an electronic one). Another goals of this site is to present the historical trajectories of modern writing systems by emphasising on their phylogenesis. Computerised writing systems and related methods (as we will see) have a long history following that of writing itself; the double-valance between the practice of writing and the mode of inscription (technologies) is an important (research) topic in the humanities (Pontin 2012; M. Kirschenbaum 2013; M. G. Kirschenbaum 2012; Kittler 1990).

                      +

                      This site is intended to introduce humanities research writers how to write text in a modern fashion using their computers. The aim of the lessons listed below are points of departure for the practice of writing text using simple, basic yet advance systems and technologies. Part of this endeavour is first and foremost to empower writers to use these systems in presenting simple didactic material working towards bootstrapping their understanding of writing technologies and help them develop a new type of literacy (albeit an electronic one). Another goals of this site is to present the historical trajectories of modern writing systems by emphasising on their phylogenesis. Computerised writing systems and related methods (as we will see) have a long history following that of writing itself; the double-valance between the practice of writing and the mode of inscription (technologies) is an important (research) topic in the humanities [@pontin_how_2012; @kirschenbaum_book-writing_2013; @kirschenbaum_mechanisms_2012; @kittler_discourse_1990].

                      Philosophy

                      The idea in compiling this site-lesson is two fold:

                      -
                        +

                        1. Present an alternative to the use of proprietary software for writing academic texts:

                          -

                          Considering the hegemonic use of proprietary software to write academic and non-academic texts (MS Word, Google Docs, Apple Pages, etc.) it is important to underline alternatives as these software not only “hide” their inner workings to scrutiny but most importantly may fall short in providing writers with adequate functionality required in writing academic texts.1 Obfuscation is impractical (and problematic) obviously so for academics in the Humanities.

                          -

                          We believe in texts that we can read, that is, we will utilise (as much as possible) software which is made “open” for us to read the source code and formats that are human-readable as opposed to solely machine-readable. Hence, throughout the lessons, we will be inspecting files and writing ones that are augmented with special codes that machines can understand. This idea of writing "meta-data" into the text or more precisely markup text in a file is very important in making sure the text is human and machine readable.

                          2. +

                          Considering the hegemonic use of proprietary software to write academic and non-academic texts (MS Word, Google Docs, Apple Pages, etc.) it is important to underline alternatives as these software not only “hide” their inner workings to scrutiny but most importantly may fall short in providing writers with adequate functionality required in writing academic texts 1. Obfuscation is impractical (and problematic) obviously so for academics in the Humanities.

                          +

                          We believe in texts that we can read, that is, we will utilise (as much as possible) software which is made “open” for us to read the source code and formats that are human-readable as opposed to solely machine-readable. Hence, throughout the lessons, we will be inspecting files and writing ones that are augmented with special codes that machines can understand. This idea of writing “meta-data” into the text or more precisely markup text in a file is very important in making sure the text is human and machine readable.

                        2. Offer a glimpse into methods, practices and systems of software writing:

                          -

                          As you may already know, writing software is primarily a textual-based practice. Writing code is all about text, keyboards, text editors, line count, syntax and the likes. Hence an important amount of systems and technologies have been devised for the composition of software (as text). From syntax highlighting to version control, these systems have a long history and can possibly provide academic writers with powerful literary tools that can enable them to bolster their prose.2 In exposing (and historicising) these systems our objective is for the reader to relate to modern software writing systems not as merely a tool but as system with a culture. In no way we expect readers to become "programmers", far from this, we would rather present them the basics of writing text using (modern) computer systems while hoping that they'll develop a critical stance on these systems' genesis, conditions, limitations and capabilites.

                          3. +

                          As you may already know, writing software is primarily a textual-based practice. Writing code is all about text, keyboards, text editors, line count, syntax and the likes. Hence an important amount of systems and technologies have been devised for the composition of software (as text). From syntax highlighting to version control, these systems have a long history and can possibly provide academic writers with powerful literary tools that can enable them to bolster their prose.2 In exposing (and historicising) these systems our objective is for the reader to relate to modern software writing systems not as merely a tool but as system with a culture. In no way we expect readers to become “programmers”, far from this, we would rather present them the basics of writing text using (modern) computer systems while hoping that they’ll develop a critical stance on these systems’ genesis, conditions, limitations and capabilites.

                        Scheme

                        -

                        The current site is segmented in six lessons covering the (very) basics of writing academic texts on a computer.3 The overall composition of these lessons is by no mean derived from obscure "Principles" or (even worst) "Best-practices" but rather stand as loosely coupled set of lessons that can be traversed all together (or not) in a short period of time. The site is neither a manual nor a manifesto and should be seen as a starting point into further developing (creative) technics and methods in text writing.

                        +

                        The current site is segmented in six lessons covering the (very) basics of writing academic texts on a computer.3 The overall composition of these lessons is by no mean derived from obscure “Principles” or (even worst) “Best-practices” but rather stand as loosely coupled set of lessons that can be traversed all together (or not) in a short period of time. The site is neither a manual nor a manifesto and should be seen as a starting point into further developing (creative) technics and methods in text writing.

                        • Lesson 1: Text Encoding

                          Covers fundamentals of representation of text looking up how text is encoded/decoded as data. We will be using Sublime Text as an editor.

                          • @@ -47,23 +44,15 @@

                          Discuss how to style (colour, margins, cover image, etc.) a given output from the text / document processor

                        As a final note worth mentioning (before delving further): all the lessons of this site, including this page, have been (are) written using the aforementioned encodings and systems. Hence, for the curious, the reader can lookup the files, modify and compile them to bootstrap their writing project. Whatever you see on this site is made available for you to read, modify, etc.

                        -
                        -

                        References

                        -

                        Cox, Geoff. 2013. Speaking Code: coding as Aesthetic and Political Expression. Software Studies. Cambridge, Mass: The MIT Press.

                        -

                        Kirschenbaum, Matthew. 2013. “The Book-Writing Machine.” Slate, March. http://www.slate.com/articles/arts/books/2013/03/len_deighton_s_bomber_the_first_book_ever_written_on_a_word_processor.html.

                        -

                        Kirschenbaum, Matthew G. 2012. Mechanisms: new Media and the Forensic Imagination. Cambridge, Mass.; London: MIT Press.

                        -

                        Kittler, Friedrich A. 1990. Discourse Networks 1800/1900. Stanford University Press.

                        -

                        Montfort, Nick. 2014. 10 PRINT CHR$(205.5+RND(1))[semi-Colon] [Colon] GOTO 10.

                        -

                        Pontin, Jason. 2012. “How Authors Write.” MIT Technology Review. http://www.technologyreview.com/review/429654/how-authors-write/.

                        -
                        -
                        +

                        References

                        +
                          -

                        1. Literally fall short of basic features– i.e. can’t format a bibliography for example– or disable these features by design as Antifeatures.↩

                          2. -

                        2. As a side note, for those who are interested in reading about code as poetry (and more) — please refer to recent work by Cox (2013) and Montfort (2014).↩

                          3. -

                        3. That is, writing text on a computers in 2015.↩

                          4. +

                        4. Literally fall short of basic features– i.e. can’t format a bibliography for example– or disable these features by design as Antifeatures.↩︎

                          5. +

                        5. As a side note, for those who are interested in reading about code as poetry (and more) — please refer to recent work by @cox_speaking_2013 and @montfort_10_2014.↩︎

                          6. +

                        6. That is, writing text on a computers in 2015.↩︎

                        -
                        + diff --git a/style/template.html5 b/style/template.html5 index 9e3cefd..5b4c5ea 100644 --- a/style/template.html5 +++ b/style/template.html5 @@ -12,9 +12,6 @@ $if(date-meta)$ $endif$ $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ - $if(quotes)$ $endif$