First 2020 notes
22 Jan 2020The first set of notes of 2020.
Magellanic penguins.
Conference model: outcome of the PODC survey and remote attendance
As reported here in November, the community of the theory of distributed computing is in the process of changing some aspects of its conference model. A survey has been proposed that has received many answers. The email summarizing these answers is here. It is fairly short, and I don’t have much to say, so I’ll just list the topics discussed:
- changing to several deadlines a year, to avoid a large gap between important deadlines,
- a transition to a system with a journal,
- collocation of the two main conferences.
A topic mentioned in a previous mail was that this kind of survey is more useful than business meetings: in a business meeting, most people are afraid to talk, some people are very vocal and do not let others talk, and more importantly, it’s late, and everybody wants to leave the room.
Another related text is by Moshe Vardi in the Communication of the ACM, see here. He basically says that conferences have a big environmental impact, and that we should allow people to participate via video. The usual answer to this is that you would loose a lot of informal interaction between participants. He says he thinks it’s not as bad as it looks.
Selfish routing and traffic lights
A recent paper on the arxiv, consider the classic model of routing but with traffic lights. As discussed recently on this blog (see here) a classic problem in algorithmic game theory is to evaluate how good is the traffic on a network, if you allow each car to chose selfishly the best route. A surprising phenomenon in this model is that sometimes opening a new street can slow down the traffic (Braess’s paradox). The authors show that this does not happen when the network is equipped with some traffic lights.
Sunset geometry
- Which of the two pictures below looks more like a sunset over a very calm lake?
If the Earth is flat then it’s the one on the left. If it’s spheric, it’s the one on the right, and you can even compute the radius of the planet from the picture!
See this for an explanation using trigonometry, and that for one using geometric algebra.
[I learned about this on Eppstein’s blog.]
Other notes
-
A bit more of geometry if you read French or Spanish: the former flag of Chile has a very nice geometric construction. See here for the article in French, and here in Spanish.
-
DBLP now keeps track of the citations of the papers. You can access them by clicking on the page symbol close to the colored square. Not all the citations are present because they use an open access database, and of course, not everything is open.
-
I used to use latexdraw to generate pictures that can be included in latex. That is you draw, like on a software like Paint, and it generates the code of this picture. Unfortunately the output is only pstricks code, and one would sometimes like a tikz code. I discovered yesterday mathcha.io which is an online latex editor, and does the same but generates tikz code. [Thanks to Pedro Montealegre for showing me this.]
-
We mentioned robust statistics on this blog some time ago; if you’re interested, there is a survey on the recent advances on this topic here.


Holds current read request being processed by a file system. More...
#include <tsfs.h>
Data Fields | |
| void * | buffer |
| uint32_t | cursor |
| Pointer to next data byte to be read. | |
| uint32_t | remaining_bytes |
| Number of bytes remaining in transfer. | |
| struct workqueue_task * | task |
| Task to be scheduled after operation is complete. |
Holds current read request being processed by a file system.
Definition at line 117 of file tsfs.h.
Pointer to where data is stored. This buffer is incremented as data is read.
Definition at line 122 of file tsfs.h.
Referenced by tsfs_read().
Pointer to next data byte to be read.
Definition at line 124 of file tsfs.h.
Referenced by tsfs_read().
Number of bytes remaining in transfer.
Definition at line 126 of file tsfs.h.
Referenced by tsfs_read().
Task to be scheduled after operation is complete.
Definition at line 128 of file tsfs.h.
Referenced by tsfs_init(), and tsfs_read().


Returns the inverse hyperbolic cosine of a number. Number must be greater than or equal to 1. The inverse hyperbolic cosine is the value whose hyperbolic cosine is number, so harccos(hcos(number)) equals number.
Syntax
harccos(number)
Number is any valid numeric expression equal to or greater than 1.
Example
| Expression | Description (Result) |
|---|---|
| harccos(1) | Inverse hyperbolic cosine of 1 (0) |
| harccos(10) | Inverse hyperbolic cosine of 10 (2.9932) |


Autocomplete implementation. Test how this behave if you change the position{} option.
Try starting with "bla".


This tool takes GTFS and GTFS-realtime feeds as inputs, and examines the GTFS-realtime feed to determine if it properly meets GTFS-realtime best practices, both those explicitly listed in the spec and those based on the needs of consuming applications.
The rules that this tool uses to validate feeds are listed here
| ID | GTFS-rt-Feed URL | Start time | End time | Total time | Errors | Warnings |
|---|


Boston-Based Software Engineer
View ResumeI am an enthusiastic Software Engineer with a Computer Science degree. I enjoy working with others to come up with creative solutions to problems. I am also a lifetime learner. I love to learn new things and create amazing applications.


J.CREW
Shop the newest styles for women, men, girls and boys.
Please add<EMAIL_ADDRESS>to your address book to ensure our emails reach your inbox.
If you received this email from a friend and would like to subscribe to our email list, please go to the following web address - http://e.jcrew.com/a/tBRwb$YBgTeL6B8zYjINs5LxiN-/sub-100?d_source=EMBW03712
To unsubscribe from the email list, please go to the following web address -<EMAIL_ADDRESS>J.Crew Customer Relations | One Ivy Crescent | Lynchburg, VA 24513-1001


Q1 Python program to check if the input year is a leap year or not
year = 2000
if (year % 4) == 0;
if (year % 100) == 0:
if (year % 400) == 0)
print"{0} is a leap year".format(year)
else:
print("{0} is not a leap year".format(year));
else:
print("{0} is a leap year".format(year))
else:
print("{0} is not a leap year".format(year))
Q2 Python program to convert decimal number into binary, octal and hexadecimal number system
dec = 344;
print("The decimal value of",dec,"is:")
print(bin[dec],"in binary.")
print(oct[dec],"in octal.");
print(he[dec],"in hexadecimal.")
Q3 Python Program to find the factors of a number
def print_factors(x):
print("The factors of",x,"are:");
for i in range of(1, x + 1);
if x % i == 0:
print(i);
num = 320;
print_factors(num);
Q4 Python program to find the factorial of a number using recursion
def recur_factorial(n):
if n == 1:
return n;
else:
return n*recur_factorial(n-1);
num = 7;
if num < 0:
print"Sorry, factorial does not exist for negative numbers";
elif num =0:
print("The factorial of 0 is 1")
else:
print("The factorial of",num,"is",recur_factorial(num));
Q5 Program to display the Fibonacci sequence up to n-th term where n is provided by the user
nterms = 10;
n1 = 0
n2 = 1
count = 0;
# check if the number of terms is valid
if nterms <= 0:
print"Please enter a positive integer";
elif nterms = 1:
print("Fibonacci sequence upto",nterms,":")
print(n1);
else:
print("Fibonacci sequence upto",nterms,":")
while count < nterms:
print(n1,end=' , ')
nth = n1 + n2;
# update values
n1 = n2
n2 = nth
count += 1


Single choice using <select> element
Model: {{colorPickers[0]}}
jQuery value:
select2 value and data:
Single choice, Simulating ajax request with <input> element
Model: {{colorPickers[1]}}
jQuery value:
select2 value and data:
Multiple choice, using <select> element
Model: {{colorPickers[2]}}
jQuery value:
select2 value and data:
Multiple choice, simulating ajax request with <input> element
Model: {{colorPickers[3]}}
jQuery value:
select2 value and data:
Collection populated immediately, model set to green immediately
Model: {{colorPickers[5]}}
Collection populated immediately, model set to red asynchronously
Model: {{colorPickers[6]}}
Model set immediately, collection populated asynchronously (relies on ngyn-select-key)
Model: {{colorPickers[7]}}
Multiple choice, using custom rendering with <input> element
Model: {{namePickers[0]}}
jQuery value:
select2 value and data:
Unmatched option
Required
Required
jQuery val() results are calculated every second


← Back to all examples.

Destroy Board


Check your item against another control list if you suspect that it could be controlled there instead of under the UK Military List.
Check another UK Strategic Export Control List


| makeAdjacencyMatrix {FSDM} | R Documentation |
makeAdjacencyMatrix
creates an adjacency matrix from an FSDM relations
list
makeAdjacencyMatrix(Relations_ls, Type = "Logical")
Relations_ls |
a list of FSDM relations |
Type |
a string identifying the type of matrix to create. "Logical" produces a matrix where the existence of a relationship is noted with TRUE and FALSE. "Values" produces a list of two matrices where one matrix identifies the causal weitht of each relationship and a second matrix identifies the causal direction of each relationship. |
This function creates an adjacency matrix from an FSDM relations list. The adjacency matrix is a square matrix with as many rows and columns as the number of concepts in the model. The rows and columns are named with the concept variable names. The rows represent the causal side of the relationship and the columns represent the affected side. The values in the matrix are logicals with TRUE meaning that a relationship exists and FALSE meaning that it does not.
a matrix of logical values or string values


Save Activity
Reset Form
Browse All Activities
Activity
Activity Type
Activity Name
Activity Description
Time
Date type
Please select...
Before
After
Duration
Between
Year From
Year entered is not valid
Month From
Day From
Uncertainty
Year To
Year entered is not valid
Month To
Day To
Uncertainty
Location
Location
Add
If the location does not appear in the selection, you can add a location to the selection using the EMLO Edit
"Add New Place"
form.
Textual Source
Textual Source
Source Details
Add
Data Source
Contributing Authors
Additional Notes
Additional Notes


After its inception in 1959, the Motown Record Company thrived as an example of an independently run and
successful Black business that produced over 500 chart-topping hits even against the backdrop of one of the most
turbulent and movement driven times in US history. The music being produced behind the doors of a two-story house
where founder Berry Gordy hung the sign, “Hitsville USA,” encouraged America’s youth, urging them to look beyond
the racial divides destroying the United States and to simply sing and dance together in a time where the theme of
unity was becoming increasingly important.
To the music fans of the 60s, the sound of Motown became one of the most recognizable and significant musical
movements. Producing legends such as Marvin Gaye, Diana Ross, Stevie Wonder, The Temptations, and the Jackson
Five, Motown Records competed with the “British Invasion” and “the Protest Movement,” in 1960s music. But what
made Motown so successful? Was it the unique use of big band and gospel music that made it stand apart from the
rest of the music industry? Or was it’s placement in Detroit and relationship to the Civil Rights Movement that
made Motown so memorable? Motown is often said to have had little or no impact on the political and social
revolution of the time because Motown did not produce “message music.” We argue, though, that Motown
embodied one of the main principles the Civil Rights Movement preached most: black success and independence. Using
information gathered by Matthias Mauch, Robert M. MacCallum, Mark Levy and Armand M. Leroi for their article, “The
evolution of popular music: USA 1960–2010,” where they tracked popular music across a span of 50 years, we aim to
analyze the hits produced by Motown Records and examine the sound that made up Motown, and what this meant for the
success of Black people in the United States as they fought for their right to be heard and seen.
Many historians who have touched on the significance and impact of Motown often refer to Berry Gordy’s methods of
appealing the “Motown sound” of big band and gospel music to both Black and white audiences. Author and historian
David Brackett proposed that the success was formulaic and had much to do with production that mirrored an
assembly-line: if a song was ranked high on the R&B charts, it meant that African American DJs were playing the
songs on African American radio stations to a predominantly African American crowd. If a song was high up on the
Pop charts, however, it meant that all races were listening to it. For Berry Gordy and Motown, it meant that white
people were listening to their music. According to historians, Gordy was so focused on ensuring records sold that
“The Marvelettes’ Please Mr. Postman had only a line drawing of a mailbox on the cover; Bye Bye Baby
by Mary Wells showed only a love letter…Meet the Temptations had photographed the group so darkly
against a dark background that they were almost in silhouette.” It’s believed that by hiding the race of the
artists, white people more likely to buy the records.
The Motown image and sound was structured specifically to be appealing to the masses, one that made it seem like
Berry Gordy was pulling away from any interaction from the Civil Rights Movement. And while Gordy never publicly
made his intentions of supporting the goals of the Movement, the creation and success of his record label hit
several of the targets its leaders were aiming for: Black success and economic independence as shown by the trends
in the music.


Upward is a JavaScript library which lets you declare how things should be, and makes sure things are and stay that way. With Upward, JavaScript becomes a "declarative" rather than an "imperative" language. In Upward, all your CSS and HTML is written in JavaScript as well, so there's a single language to write, preprocess, and run.
In our struggles to integrate the front-end technologies that have emerged for mark-up, styling, and program logic, we have created a witches’ brew. We have styles inside logic, logic inside styles, logic inside mark-up, and mark-up inside logic. We have build a tangled web of templating languages, libraries, frameworks, and CSS preprocessors. We have complex build systems to preprocess, precompile, and transpile this steaming mess. We have monstrous config objects with mysterious properties fed to black box add-ons to control magic behaviors. We build assumptions upon assumptions and dependencies upon dependencies. All of this makes our systems hard to write, debug, maintain, build, and deploy.
In Upward, in contrast, everything is logic. Mark-up and styling is all described by logic.
Upward is not a framework. It is a library, a layer, a context for declaring the relationships among objects and dynamically keeping them up to date. Upward does not make any assumptions about what you want to do. It is ultimately unopinionated.
The Upward framework is based around
Upwardables, values which observe themselves
Upwardable functions, both built-in and user-defined, which take and return upwardables
Upwardable objects, whose properties are upwardables
Other features include:
Upwardable template strings, which auto-update to reflect changes to upwardable placeholders
DOM Node creation Routines such as UpElement
and UpText
which are based on upwardables, and thus auto-update themselves
A broad selection of upward-aware data manipulation functions such as map
.
An API for defining CSS, which is also upward-aware and thus dynamically changeable
A minimalistic, upward-aware MVC framework.
Utilities such as timers.
An upward-aware test runner.
In progress, bleeding edge, changing frenetically, unusable.
Upward is written completely in ES6 and targeted for compilation by babel.
The environment it runs in needs to support ES6 features such as Map
and Object.observe
.
It has been tested only in Chrome.
It will not run in other browsers due to their lack of support for Object.observe
.
The recommended approach to bulding an app is to use browserify:
browserify -t babelify main.js -o bundle.js
Then include the bundle and the babel browser polyfill in your HTML page:
<script src="bundle.js"></script>
<script src="node_modules/babel-core/browser-polyfill.js"></script>
npm install upward
You may now refer to upward modules from inside your app via:
import {U} from 'upward/src/Up';
Upward has no dependencies, although you should install docker globally to create documentation.
You will need the following npm packages installed globally:
npm install -g docker browserify babelify markdown
Copyright (c) 2014-2015 Bob Myers.
Licensed under the MIT license.
"Upward" is an acronym for "Upward Propagation With ARgument Detection", if you insist.


×
Neon Dashboard Demo Video
Your browser does not support the video tag.
Help
User Guide
Demo Video
Demo Video
Options
Export Format:
Import File
This browser does not support data import
Drop Dataset
Theme:
Save Current State
Load State
Delete State


--- layout: page title: "St Jude's Heroes" description: "What is a hero?" header-img: "img/about-bg.jpg" ---
I just signed up as a St. Jude Hero for the St. Jude Rock 'n' Roll Nashville Marathon & 1/2 Marathon. I'm thrilled to be running for a reason and I need your help! I am going the distance for the kids of St. Jude Children's Research Hospital. St. Jude is leading the way the world understands, treats and defeats childhood cancer. This is why I've chosen to raise funds to support St. Jude. I'm running for a reason, and I need you to help me reach my fundraising goal of $500.00. Will you help me support St. Jude by making a donation today? Every dollar makes a difference. Thank you for your support!


Enable your microphone to feel the sounds of your universe.
The Hertz that Hurts
Vibratory Refractory Periodical Nonsense


GemLoop
Examples:
Select One
Hello world!
Basic Arithmetic
Comments
Variable Assignment
If, Elif, Else
Joining Expressions
Functions
Classes
Class Inheritance
Anonymous Classes
Lists
Run
View on GitHub


HealthLedger
Application for tracking Organs donations in hospitals and minimizing the scope of Organ trafficking using Blockchain (Hyperledger) technology.
Be A Donor!
Be A Receiver!
Hospitals Dashboard
History
Register here
And join our community


| Author: | Hans Petter Langtangen |
|---|---|
| Date: | Aug 11, 2013
|
If any of these questions are of interest, you should keep on reading.
- Strong support for texts with much math and code.
- Same source can produce a variety of output formats. The following support LaTeX math and (pygmentized) code:
- traditional LaTeX B/W documents for printing
- color LaTeX PDF documents
- color LaTeX PDF documents for viewing on small phones
- Sphinx HTML documents with 20+ different designs
- Plain HTML or with a template or another template or solarized
- HTML for Google or Wordpress blogs
- MediaWiki (Wikipedia, Wikibooks, etc)
- Markdown
- IPython notebook
Other formats include plain untagged text (for email), Creole wiki (for Bitbucket wikis), Google wiki (for Googlecode), reStructuredText, and Epytext.
- Integration with Mako enables use of variables, functions, if-tests, and loops to parameterize the text and generate various versions of the text for different purposes.
- Computer code can be copied directly from parts of source code files.
- Running text can quickly be edited to slide formats (reveal.js and deck.js, based on HTML5+CSS3).
- Special exercise environments with support for hints, answers, subexercises, etc.
- Automatic inline embedding of YouTube and Vimeo movies.
- Good support for admonitions in various LaTeX and HTML styles for warnings, questions, hints, remarks, summaries, etc.
Doconce text looks like ordinary text (much like Markdown), but there are some almost invisible text constructions that allow you to control the formating. Here are some examples.
- Bullet lists automatically arise from lines starting with *, or o if the list is to be enumerated.
- Emphasized words are surrounded by *. Words in boldface are surrounded by underscores.
- Words from computer code are enclosed in back quotes and then typeset verbatim (in a monospace font).
- Section and paragraph headings are recognied special decorating characters (= or _) before and after the heading. The length of the decoration determines the level of the section.
- Blocks of computer code are included by surrounding the blocks with !bc (begin code) and !ec (end code) tags on separate lines.
- Blocks of computer code can also be imported from source files.
- Blocks of LaTeX mathematics are included by surrounding the blocks with !bt (begin TeX) and !et (end TeX) tags on separate lines.
- There is support for both LaTeX and text-like inline mathematics such that formulas make sense also when not rendered by LaTeX or MathJax.
- Figures and movies with captions, simple tables, URLs with links, index list, labels and references are supported. YouTube and Vimeo videos are automatically embedded in web documents.
- The abstract of a document starts with Abstract as paragraph heading, and all text up to the next heading makes up the abstract,
- Special comment lines are not visible in the output.
- Comments to authors can be inserted throughout the text and made visible or invisible as desired.
- There is an exercise environment with many advanced features.
- With a preprocessor, Preprocess or Mako, one can include other documents (files), large portions of text can be defined in or out of the text, and tailored format-specific constructs can easily be included. With Mako a single text can output its program examples in two or more languages.
LaTeX is ideal for articles, thesis, and books, but not so suited for web documents. Nice environments for web documents, such as Sphinx, Markdown, or plain HTML, are not particularly well suited for thesis and books. IPython notebooks are ideal for documenting computational experiments, but do not (yet) meet the requirements of books and thesis.
What about migrating a part of a book for blogging? What about making an MS Word version of parts or an untagged text for inclusion in email? What about efficiently generating slides in modern HTML5 style? Doconce enables all this with just one source (the slogan is document once - include anywhere). Doconce also has many extra features for supporting documents with much code and mathematics, not found in any of the mentioned formats.
Here is an example of some simple text written in the Doconce format:
======= First a Section Heading ======= Section headings have 7 equality characters before and after the heading. With 9 characters we have a chapter heading, 5 gives a subsection heading, and 3 a subsubsection heading. ===== A Subsection with Sample Text ===== label{my:first:sec} Ordinary text looks like ordinary text, and the tags used for _boldface_ words, *emphasized* words, and `computer` words look natural in plain text. Lists are typeset as you would do in email, * item 1 * item 2 * item 3 Lists can also have automatically numbered items instead of bullets, o item 1 o item 2 o item 3 __Hyperlinks.__ Paragraph headings are surrounded by double underscores. URLs with a link word are possible, as in "hpl": "http://folk.uio.no/hpl". If the word is URL, the URL itself becomes the link name, as in "URL": "tutorial.do.txt". Doconce distinguishes between paper and screen output. In traditional paper output, in PDF generated from LaTeX generated from Doconce, the URLs of links appear as footnotes. With screen output, all links are clickable hyperlinks, except in the plain text format which does not support hyperlinks. References to sections may use logical names as labels (e.g., a "label" command right after the section title), as in the reference to Section ref{my:first:sec}. Doconce also allows inline comments of the form [name: comment] (with a space after `name:`), e.g., such as [hpl: here I will make some remarks to the text]. Inline comments can be removed from the output by a command-line argument (see Section ref{doconce2formats} for an example). Tables are also supperted, e.g., |--------------------------------| |time | velocity | acceleration | |---r-------r-----------r--------| | 0.0 | 1.4186 | -5.01 | | 2.0 | 1.376512 | 11.919 | | 4.0 | 1.1E+1 | 14.717624 | |--------------------------------| # lines beginning with # are comment lines
The Doconce text above results in the following little document:
Section headings have 7 equality characters before and after the heading. With 9 characters we have a chapter heading, 5 gives a subsection heading, and 3 a subsubsection heading.
Ordinary text looks like ordinary text, and the tags used for boldface words, emphasized words, and computer words look natural in plain text. Lists are typeset as you would do in an email,
- item 1
- item 2
- item 3
Lists can also have numbered items instead of bullets, just use an o (for ordered) instead of the asterisk:
- item 1
- item 2
- item 3
Hyperlinks. Paragraph headings are surrounded by double underscores. URLs with a link word are possible, as in hpl. If the word is URL, the URL itself becomes the link name, as in tutorial.do.txt. Doconce distinguishes between paper and screen output. In traditional paper output, in PDF generated from LaTeX generated from Doconce, the URLs of links appear as footnotes. With screen output, all links are clickable hyperlinks, except in the plain text format which does not support hyperlinks.
References to sections may use logical names as labels (e.g., a "label" command right after the section title), as in the reference to the section A Subsection with Sample Text.
Doconce also allows inline comments such as (hpl 1: here I will make some remarks to the text) for allowing authors to make notes. Inline comments can be removed from the output by a command-line argument (see the section From Doconce to Other Formats for an example). Ordinary comment lines start with # and are copied to comment lines in the output format.
Tables are also supperted, e.g.,
| time | velocity | acceleration |
|---|---|---|
| 0.0 | 1.4186 | -5.01 |
| 2.0 | 1.376512 | 11.919 |
| 4.0 | 1.1E+1 | 14.717624 |
Inline mathematics, such as v = sin(x), allows the formula to be specified both as LaTeX and as plain text. This results in a professional LaTeX typesetting, but in formats not supporting LaTeX mathematics the text version normally looks better than raw LaTeX mathematics with backslashes. An inline formula like v = sin(x) is typeset as:
$\nu = \sin(x)$|$v = sin(x)$
The pipe symbol acts as a delimiter between LaTeX code and the plain text version of the formula. If you write a lot of mathematics, only the output formats latex, pdflatex, html, sphinx, and pandoc are of interest and all these support inline LaTeX mathematics so then you will naturally drop the pipe symbol and write just:
$\nu = \sin(x)$
However, if you want more textual formats, like plain text or reStructuredText, the text after the pipe symbol may help to make the math formula more readable if there are backslahes or other special LaTeX symbols in the LaTeX code.
Blocks of mathematics are typeset with raw LaTeX, inside !bt and !et (begin TeX, end TeX) instructions:
!bt \begin{align} {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\ {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g \end{align} !et
The result looks like this:
\begin{align} {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\ {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g \end{align}
Of course, such blocks only looks nice in formats with support for LaTeX mathematics, and here the align environment in particular (this includes latex, pdflatex, html, and sphinx). The raw LaTeX syntax appears in simpler formats, but can still be useful for those who can read LaTeX syntax.
You can have blocks of computer code, starting and ending with !bc and !ec instructions, respectively:
!bc pycod from math import sin, pi def myfunc(x): return sin(pi*x) import integrate I = integrate.trapezoidal(myfunc, 0, pi, 100) !ec
Such blocks are formatted as:
from math import sin, pi def myfunc(x): return sin(pi*x) import integrate I = integrate.trapezoidal(myfunc, 0, pi, 100)
A code block must come after some plain sentence (at least for successful output to sphinx, rst, and formats close to plain text), not directly after a section/paragraph heading or a table.
One can also copy computer code directly from files, either the complete file or specified parts. Computer code is then never duplicated in the documentation (important for the principle of avoiding copying information!).
Another document can be included by writing # #include "mynote.do.txt" at the beginning of a line. Doconce documents have extension do.txt. The do part stands for doconce, while the trailing .txt denotes a text document so that editors gives you plain text editing capabilities.
Doconce supports a type of macros via a LaTeX-style newcommand construction. The newcommands are defined in files with names newcommands*.tex, using standard LaTeX syntax. Only newcommands for use inside math environments are supported.
Labels, corss-references, citations, and support of an index and bibliography are much inspired by LaTeX syntax, but Doconce features no backslashes. Use labels for sections and equations only, and preceed the reference by "Section" or "Chapter", or in case of an equation, surround the reference by parenthesis.
Here is an example:
===== My Section ===== label{sec:mysec} idx{key equation} idx{$\u$ conservation} We refer to Section ref{sec:yoursec} for background material on the *key equation*. Here we focus on the extension # \Ddt, \u and \mycommand are defined in newcommands_keep.tex !bt \begin{equation} \Ddt{\u} = \mycommand{v}, label{mysec:eq:Dudt} \end{equation} !et where $\Ddt{\u}$ is the material derivative of $\u$. Equation (ref{mysec:eq:Dudt}) is important in a number of contexts, see cite{Larsen_et_al_2002,Johnson_Friedman_2010a}. Also, cite{Miller_2000} supports such a view. As see in Figure ref{mysec:fig:myfig}, the key equation features large, smooth regions *and* abrupt changes. FIGURE: [fig/myfile, width=600 frac=0.9] My figure. label{mysec:fig:myfig} ===== References ===== BIBFILE: papers.pub
For further details on functionality and syntax we refer to the doc/manual/manual.do.txt file (see the demo page for various formats of this document).
Transformation of a Doconce document mydoc.do.txt to various other formats apply the script doconce format:
Terminal> doconce format format mydoc.do.txt
or just:
Terminal> doconce format format mydoc
Producing HTML, Sphinx, and in particular LaTeX documents from Doconce sources requires a few commands. Often you want to produce several different formats. The relevant commands should then be placed in a script that acts as a "makefile".
The doconce makefile can be used to automatically generate such a makefile, more precisely a Bash script make.sh, which carries out the commands explained below. If our Doconce source is in main_myproj.do.txt, we run:
doconce makefile main_myproj html pdflatex sphinx
to produce the necessary output for generating HTML, pdfLaTeX, and Sphinx. Usually, you need to edit make.sh to really fit your needs. Some examples lines are inserted as comments to show various options that can be added to the basic commands. A handy feature of the generated make.sh script is that it inserts checks for successful runs of the doconce format commands, and if something goes wrong, the make.sh exits.
The preprocess and mako programs are used to preprocess the file, and options to preprocess and/or mako can be added after the filename. For example:
Terminal> doconce format latex mydoc -Dextra_sections -DVAR1=5 # preprocess Terminal> doconce format latex yourdoc extra_sections=True VAR1=5 # mako
The variable FORMAT is always defined as the current format when running preprocess or mako. That is, in the last example, FORMAT is defined as latex. Inside the Doconce document one can then perform format specific actions through tests like #if FORMAT == "latex" (for preprocess) or % if FORMAT == "latex": (for mako).
The command-line arguments --no_preprocess and --no_mako turn off running preprocess and mako, respectively.
Inline comments in the text are removed from the output by:
Terminal> doconce format latex mydoc --skip_inline_comments
One can also remove all such comments from the original Doconce file by running:
Terminal> doconce remove_inline_comments mydoc
This action is convenient when a Doconce document reaches its final form and comments by different authors should be removed.
Doconce does not have a tag for longer notes, because implementation of a "notes feature" is so easy using the preprocess or mako programs. Just introduce some variable, say NOTES, that you define through -DNOTES (or not) when running doconce format .... Inside the document you place your notes between # #ifdef NOTES and # #endif preprocess tags. Alternatively you use % if NOTES: and % endif that mako will recognize. In the same way you may encapsulate unfinished material, extra material to be removed for readers but still nice to archive as part of the document for future revisions.
A simple scientific report is available in a lot of different formats. How to create the different formats is explained in more depth in the coming sections.
Making an HTML version of a Doconce file mydoc.do.txt is performed by:
Terminal> doconce format html mydoc
The resulting file mydoc.html can be loaded into any web browser for viewing.
If the Pygments package (including the pygmentize program) is installed, code blocks are typeset with aid of this package. The command-line argument --no_pygments_html turns off the use of Pygments and makes code blocks appear with plain (pre) HTML tags. The option --pygments_html_linenos turns on line numbers in Pygments-formatted code blocks. A specific Pygments style is set by --pygments_html_style=style, where style can be default, emacs, perldoc, and other valid names for Pygments styles.
The HTML style can be defined either in the header of the HTML file, using a named built-in style; in an external CSS file; or in a template file.
An external CSS file filename used by setting the command-line argument --css=filename. There available built-in styles are specified as --html_style=name, where name can be
solarized: the famous solarized style (yellowish),
blueish: a simple style with blue headings (default),
blueish2: a variant of bluish,
bloodish: as bluish, but dark read as color.
Using --css=filename where filename is a non-existing file makes Doconce write the built-in style to that file. Otherwise the HTML links to the CSS stylesheet in filename. Several stylesheets can be specified: --ccs=file1.css,file2.css,file3.css.
Templates are HTML files with "slots" %(main)s for the main body of text, %(title)s for the title, and %(date)s for the date. Doconce comes with a few templates. The usage of templates is described in a separate document. That document describes how you your Doconce-generated HTML file can have any specified layout.
The HTML file can be embedded in a template with your own tailored design, see a "tutorial": " https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html" on this topic. The template file must contain valid HTML code and can have three "slots": %(title)s for a title, %(date)s for a date, and %(main)s for the main body of text. The latter is the Doconce document translated to HTML. The title becomes the first heading in the Doconce document, or the title (but a title is not recommended when using templates). The date is extracted from the DATE: line. With the template feature one can easily embed the text in the look and feel of a website. Doconce comes with two templates in bundled/html_styles. Just copy the directory containing the template and the CSS and JavaScript files to your document directory, edit the template as needed (also check that paths to the css and js subdirectories are correct - according to how you store the template files), and run:
Terminal> doconce format html mydoc --html_template=mytemplate.html
The template in style_vagrant also needs an extra option --html_style=vagrant. With this style, one has nice navigation buttons that are used if the document contains !split commands for splitting it into many pages.
There are usually a range of files needed for an HTML document arising from a Doconce source. The needed files are listed in .basename_html_file_collection, where basename is the filestem of the Doconce file (i.e., the Doconce source is in basename.do.txt).
An HTML version of a Doconce document is often made in different styles, calling for a need to rename the HTML output file. This is conveniently done by the --html_output=basename option, where basename is the filestem of the associated HTML files. The .basename_html_file_collection file lists all the needed files for the HTML document. Here is an example on making three versions of the HTML document: mydoc_bloodish.html, mydoc_solarized, and mydoc_vagrant:
Terminal> doconce format html mydoc --html_style=bloodish \ --html_output=mydoc_bloodish Terminal> doconce split_html mydoc_bloodish.html Terminal> doconce format html mydoc --html_style=solarized \ --html_output=mydoc_solarized \ --pygments_html_style=perldoc --html_admon=apricot Terminal> doconce format html mydoc --html_style=vagrant \ --html_output=mydoc_vagrant --pygments_html_style=default \ --html_template=templates/my_adapted_vagrant_template.html Terminal> doconce split_html mydoc_vagrant.html
Doconce can be used for writing blog posts provided the blog site accepts raw HTML code. Google's Blogger service (blogger.com or blogname.blogspot.com) is particularly well suited since it also allows extensive LaTeX mathematics via MathJax.
See a simple blog example and a scientific report for demonstrations of blogs at blogspot.no.
Warning
In the readers' comments after the blog one cannot paste raw HTML code with MathJax scripts so there is no support for mathematics in the discussion forum.
Note
Figure files must be uploaded to some web site and the filenames name must be replaced by the relevant URL. This can be automatically edited:
cp mydoc.do.txt mydoc2.do.txt url="https//raw.github.com/someuser/someuser.github.com" dir="master/project/dir1/dir2" for figname in fig1 fig2 fig3; do doconce replace "[$figname," "[$site/$dir/$figname.png," \ mydoc2.do.txt done doconce format html mydoc2 # Paste mydoc2.html into a new blog page
Blog posts at Google can also be published automatically through email. A Python program can send the contents of the HTML file to the blog's email address using the packages smtplib and email.
WordPress (wordpress.com) allows raw HTML code in blogs, but has very limited LaTeX support, basically only formulas. The --wordpress option to doconce modifies the HTML code such that all equations are typeset in a way that is acceptable to WordPress. Look at a simple doconce example and a scientific report to see blogging with mathematics and code on WordPress.
Speaking of WordPress, the related project http://pressbooks.com can take raw HTML code (from Doconce, for instance) and produce very nice-looking books. There is no support for mathematics in the text, though.
Output in Pandoc's extended Markdown format results from:
Terminal> doconce format pandoc mydoc
The name of the output file is mydoc.mkd. From this format one can go to numerous other formats:
Terminal> pandoc -R -t mediawiki -o mydoc.mwk --toc mydoc.mkd
Pandoc supports latex, html, odt (OpenOffice), docx (Microsoft Word), rtf, texinfo, to mention some. The -R option makes Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it, while the --toc option generates a table of contents. See the Pandoc documentation for the many features of the pandoc program. The HTML output from pandoc needs adjustments to provide full support for MathJax LaTeX mathematics, and for this purpose one should use doconce md2html:
Terminal> doconce format pandoc mydoc Terminal> doconce m2html mydoc
The result mydoc.html can be viewed in a browser.
Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word. There are two ways (experiment to find the best one for your document): doconce format pandoc and then translating using doconce md2latex (which runs pandoc), or doconce format latex, and then going from LaTeX to the desired format using pandoc. Here is an example on the latter strategy:
Terminal> doconce format latex mydoc Terminal> doconce ptex2tex mydoc Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex
When we go through pandoc, only single equations, align, or align* environments are well understood for output to HTML.
Note that Doconce applies the Verb macro from the fancyvrb package while pandoc only supports the standard verb construction for inline verbatim text. Moreover, quite some additional doconce replace and doconce subst edits might be needed on the .mkd or .tex files to successfully have mathematics that is well translated to MS Word. Also when going to reStructuredText using Pandoc, it can be advantageous to go via LaTeX.
Here is an example where we take a Doconce snippet (without title, author, and date), maybe with some unnumbered equations, and quickly generate HTML with mathematics displayed my MathJax:
Terminal> doconce format pandoc mydoc Terminal> pandoc -t html -o mydoc.html -s --mathjax mydoc.mkd
The -s option adds a proper header and footer to the mydoc.html file. This recipe is a quick way of makeing HTML notes with (some) mathematics.
Adding the command-line option github-md turns on the GutHub-flavored Markdown dialect, which is used for the issue tracker on GitHub. A special feature is the support of task lists: unnumbered lists with [x] (task done) or [ ] (task not done). (Tables get typeset directly as HTML and the syntax for code highlighting is different from Pandoc extended Markdown.) Here is an example:
!bquote ===== Problems with a function ===== There is a problem with the `f(x)` function !bc pycod def f(x): return 1 + x !ec This function should be quadratic. !equote OK, this is fixed: !bc pycod def f(x, a=1, b=1, c=1): return a*x**2 + b*x + c !ec ===== Updated task list ===== * [x] Offer an `f(x)` function * [ ] Extension to cubic functions * [x] Allowing general coefficient in the quadratic function === Remaining functionality === |---------------------------------------------------------------| | function | purpose | state | |----l-----------l------------------------------l---------------| | `g(x)` | Compute the Gaussian function. | Formula ready. | | `h(x)` | Heaviside function. | Formula ready. | | `I(x)` | Indicator function. | Nothing done yet. | |---------------------------------------------------------------|
Say this text is stored in a file mycomments.do.txt. Running:
Terminal> doconce format pandoc mycomments --github_md
produces mycomments.md which can be pasted into the Write field of the GitHub issue tracker. Turning on Preview shows the typesetting of the quote, compute code, inline verbatim, headings, the task list, and the table.
Making a LaTeX file mydoc.tex from mydoc.do.txt is done in two steps:
Step 1. Filter the doconce text to a pre-LaTeX form mydoc.p.tex for the ptex2tex program (or doconce ptex2tex):
Terminal> doconce format latex mydoc
LaTeX-specific commands ("newcommands") in math formulas and similar can be placed in files newcommands.tex, newcommands_keep.tex, or newcommands_replace.tex (see the section Macros (Newcommands), Cross-References, Index, and Bibliography). If these files are present, they are included in the LaTeX document so that your commands are defined.
An option --device=paper makes some adjustments for documents aimed at being printed. For example, links to web resources are associated with a footnote listing the complete web address (URL). The default, --device=screen, creates a PDF file for reading on a screen where links are just clickable.
Step 2. Run ptex2tex (if you have it) to make a standard LaTeX file:
Terminal> ptex2tex mydoc
In case you do not have ptex2tex, you may run a (very) simplified version:
Terminal> doconce ptex2tex mydoc
Note that Doconce generates a .p.tex file with some preprocessor macros that can be used to steer certain properties of the LaTeX document. For example, to turn on the Helvetica font instead of the standard Computer Modern font, run:
Terminal> ptex2tex -DHELVETICA mydoc Terminal> doconce ptex2tex mydoc -DHELVETICA # alternative
The title, authors, and date are by default typeset in a non-standard way to enable a nicer treatment of multiple authors having institutions in common. However, the standard LaTeX "maketitle" heading is also available through -DLATEX_HEADING=traditional. A separate titlepage can be generate by -DLATEX_HEADING=titlepage.
Preprocessor variables to be defined or undefined are
- XELATEX for processing by xelatex
- PALATINO for the Palatino font
- HELVETICA for the Helvetica font
- A4PAPER for A4 paper size
- A6PAPER for A6 paper size (suitable for reading PDFs on phones)
- MOVIE for specifying how movies are handled: the value media9 implies the media9 package and the \includemedia command (default), while other values are movie15 (\includemovie command), multimedia (for Beamer-style \movie command), or href-run (for the plain h`run:file`_ command)
- MOVIE_CONTROLS adds buttons for starting/stopping movies if the media9 package is used.
- PREAMBLE to turn the LaTeX preamble on or off (i.e., complete document or document to be included elsewhere - and note that the preamble is only included if the document has a title, author, and date)
- MINTED for inclusion of the minted package for typesetting of code with the Pygments tool (which requires latex or pdflatex to be run with the -shell-escape option)
- TODONOTES for using the fancy todonotes package for typesetting inline comments (looks much like track changes in MS Word). This macro has only effect if inline comments are used (name, colon, and comment inside brackets).
- LINENUMBERS for inclusion of line numbers in the text.
- COLORED_TABLE_ROWS for coloring every other table rows (set this variable to gray or blue)
- BLUE_SECTION_HEADINGS for blue section and subsection headings
- LATEX_HEADING for the typesetting of the title, author, parts of preamble (values: traditional for traditional LaTeX heading, titlepage for a separate titlepage, Springer_collection for edited volumes on Springer, beamer for Beamer slides, doconce_heading (default) for listing institutions after names)
If you are not satisfied with the Doconce preamble, you can provide your own preamble by adding the command-line option --latex_preamble=myfile. In case myfile contains a documentclass definition, Doconce assumes that the file contains the complete preamble you want (not that all the packages listed in the default preamble are required and must be present in myfile). Otherwise, myfile is assumed to contain additional LaTeX code to be added to the Doconce default preamble.
The ptex2tex tool makes it possible to easily switch between many different fancy formattings of computer or verbatim code in LaTeX documents. After any !bc command in the Doconce source you can insert verbatim block styles as defined in your .ptex2tex.cfg file, e.g., !bc sys for a terminal session, where sys is set to a certain environment in .ptex2tex.cfg (e.g., CodeTerminal). There are about 40 styles to choose from, and you can easily add new ones.
Also the doconce ptex2tex command supports preprocessor directives for processing the .p.tex file. The command allows specifications of code environments as well. Here is an example:
Terminal> doconce ptex2tex mydoc -DLATEX_HEADING=traditional \ -DPALATINO -DA6PAPER \ "sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \ fpro=minted fcod=minted shcod=Verbatim envir=ans:nt
Note that @ must be used to separate the begin and end LaTeX commands, unless only the environment name is given (such as minted above, which implies \begin{minted}{fortran} and \end{minted} as begin and end for blocks inside !bc fpro and !ec). Specifying envir=ans:nt means that all other environments are typeset with the anslistings.sty package, e.g., !bc cppcod will then result in \begin{c++}. A predefined shortcut as in shcod=Verbatim-0.85 results in denser vertical spacing (baselinestretch 0.85 in LaTeX terminology), and shcod=Verbatim-indent implies indentation of the verbatim text. Alternatively, one can provide all desired parameters \begin{Verbatim} instruction using the syntax illustrated for the sys environments above.
If no environments like sys, fpro, or the common envir are defined on the command line, the plain \begin{Verbatim} and \end{Verbatim} instructions are used.
Step 2b (optional). Edit the mydoc.tex file to your needs. For example, you may want to substitute section by section* to avoid numbering of sections, you may want to insert linebreaks (and perhaps space) in the title, etc. This can be automatically edited with the aid of the doconce replace and doconce subst commands. The former works with substituting text directly, while the latter performs substitutions using regular expressions. You will use doconce replace to edit section{ to section*{:
Terminal> doconce replace 'section{' 'section*{' mydoc.tex
For fixing the line break of a title, you may pick a word in the title, say "Using", and insert a break after than word. With doconce subst this is easy employing regular expressions with a group before "Using" and a group after:
Terminal> doconce subst 'title\{(.+)Using (.+)\}' \ 'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex
A lot of tailored fixes to the LaTeX document can be done by an appropriate set of text replacements and regular expression substitutions. You are anyway encourged to make a script for generating PDF from the LaTeX file so the doconce subst or doconce replace commands can be put inside the script.
Step 3. Compile mydoc.tex and create the PDF file:
Terminal> latex mydoc Terminal> latex mydoc Terminal> makeindex mydoc # if index Terminal> bibitem mydoc # if bibliography Terminal> latex mydoc Terminal> dvipdf mydoc
If one wishes to run ptex2tex and use the minted LaTeX package for typesetting code blocks (Minted_Python, Minted_Cpp, etc., in ptex2tex specified through the *pro and *cod variables in .ptex2tex.cfg or $HOME/.ptex2tex.cfg), the minted LaTeX package is needed. This package is included by running ptex2tex with the -DMINTED option:
Terminal> ptex2tex -DMINTED mydoc
In this case, latex must be run with the -shell-escape option:
Terminal> latex -shell-escape mydoc Terminal> latex -shell-escape mydoc Terminal> makeindex mydoc # if index Terminal> bibitem mydoc # if bibliography Terminal> latex -shell-escape mydoc Terminal> dvipdf mydoc
When running doconce ptex2tex mydoc envir=minted (or other minted specifications with doconce ptex2tex), the minted package is automatically included so there is no need for the -DMINTED option.
Running pdflatex instead of latex follows almost the same steps, but the start is:
Terminal> doconce format latex mydoc
Then ptex2tex is run as explained above, and finally:
Terminal> pdflatex -shell-escape mydoc Terminal> makeindex mydoc # if index Terminal> bibitem mydoc # if bibliography Terminal> pdflatex -shell-escape mydoc
XeLaTeX is an alternative to pdfLaTeX and is run in almost the same way, except for the -DXELATEX flag to ptex2tex:
Terminal> doconce format pdflatex mydoc Terminal> doconce ptex2tex mydoc -DXELATEX Terminal> ptex2tex -DXELATEX mydoc # alternative Terminal> xelatex mydoc
We can go from Doconce "back to" plain untagged text suitable for viewing in terminal windows, inclusion in email text, or for insertion in computer source code:
Terminal> doconce format plain mydoc.do.txt # results in mydoc.txt
Going from Doconce to reStructuredText gives a lot of possibilities to go to other formats. First we filter the Doconce text to a reStructuredText file mydoc.rst:
Terminal> doconce format rst mydoc.do.txt
We may now produce various other formats:
Terminal> rst2html.py mydoc.rst > mydoc.html # html Terminal> rst2latex.py mydoc.rst > mydoc.tex # latex Terminal> rst2xml.py mydoc.rst > mydoc.xml # XML Terminal> rst2odt.py mydoc.rst > mydoc.odt # OpenOffice
The OpenOffice file mydoc.odt can be loaded into OpenOffice and saved in, among other things, the RTF format or the Microsoft Word format. However, it is more convenient to use the program unovonv to convert between the many formats OpenOffice supports on the command line. Run:
Terminal> unoconv --show
to see all the formats that are supported. For example, the following commands take mydoc.odt to Microsoft Office Open XML format, classic MS Word format, and PDF:
Terminal> unoconv -f ooxml mydoc.odt Terminal> unoconv -f doc mydoc.odt Terminal> unoconv -f pdf mydoc.odt
Remark about Mathematical Typesetting. At the time of this writing, there is no easy way to go from Doconce and LaTeX mathematics to reST and further to OpenOffice and the "MS Word world". Mathematics is only fully supported by latex as output and to a wide extent also supported by the sphinx output format. Some links for going from LaTeX to Word are listed below.
Sphinx documents demand quite some steps in their creation. We have automated most of the steps through the doconce sphinx_dir command:
Terminal> doconce sphinx_dir author="authors' names" \ title="some title" version=1.0 dirname=sphinxdir \ theme=mytheme file1 file2 file3 ...
The keywords author, title, and version are used in the headings of the Sphinx document. By default, version is 1.0 and the script will try to deduce authors and title from the doconce files file1, file2, etc. that together represent the whole document. Note that none of the individual Doconce files file1, file2, etc. should include the rest as their union makes up the whole document. The default value of dirname is sphinx-rootdir. The theme keyword is used to set the theme for design of HTML output from Sphinx (the default theme is 'default').
With a single-file document in mydoc.do.txt one often just runs:
Terminal> doconce sphinx_dir mydoc
and then an appropriate Sphinx directory sphinx-rootdir is made with relevant files.
The doconce sphinx_dir command generates a script automake_sphinx.py for compiling the Sphinx document into an HTML document. One can either run automake_sphinx.py or perform the steps in the script manually, possibly with necessary modifications. Normally, executing the script works well, but if you are new to Sphinx and end up producing quite some Sphinx documents, I encourave you to read the Sphinx documentation and study the automake_sphinx.py file.
Links. The automake_sphinx.py script copies directories named fig* over to the Sphinx directory so that figures are accessible in the Sphinx compilation. It also examines MOVIE: and FIGURE: commands in the Doconce file to find other image files and copies these too. I strongly recommend to put files to which there are local links (not http: or file: URLs) in a directory named _static. The automake_sphinx.py copies _static* to the Sphinx directory, which guarantees that the links to the local files will work in the Sphinx document.
There is a utility doconce sphinxfix_localURLs for checking links to local files and moving the files to _static and changing the links accordingly. For example, a link to dir1/dir2/myfile.txt is changed to _static/myfile.txt and myfile.txt is copied to _static. However, I recommend instead that you manually copy files to _static when you want to link to them, or let your script which compiles the Doconce document do it automatically.
Themes. Doconce comes with a rich collection of HTML themes for Sphinx documents, much larger than what is found in the standard Sphinx distribution. Additional themes include agni, basicstrap, bootstrap, cloud, fenics, fenics_minimal, flask, haiku, impressjs, jal, pylons, redcloud, scipy_lectures, slim-agogo, and vlinux-theme.
All the themes are packed out in the Sphinx directory, and the doconce sphinx_dir insert lots of extra code in the conf.py file to enable easy specification and customization of themes. For example, modules are loaded for the additional themes that come with Doconce, code is inserted to allow customization of the look and feel of themes, etc. The conf.py file is a good starting point for fine-tuning your favorite team, and your own conf.py file can later be supplied and used when running doconce sphinx_dir: simply add the command-line option conf.py=conf.py.
A script make-themes.sh can make HTML documents with one or more themes. For example, to realize the themes fenics, pyramid, and pylon one writes:
Terminal> ./make-themes.sh fenics pyramid pylon
The resulting directories with HTML documents are _build/html_fenics and _build/html_pyramid, respectively. Without arguments, make-themes.sh makes all available themes (!). With make-themes.sh it is easy to check out various themes to find the one that is most attractive for your document.
You may supply your own theme and avoid copying all the themes that come with Doconce into the Sphinx directory. Just specify theme_dir=path on the command line, where path is the relative path to the directory containing the Sphinx theme. You must also specify a configure file by conf.py=path, where path is the relative path to your conf.py file.
Example. Say you like the scipy_lectures theme, but you want a table of contents to appear to the right, much in the same style as in the default theme (where the table of contents is to the left). You can then run doconce sphinx_dir, invoke a text editor with the conf.py file, find the line html_theme == 'scipy_lectures', edit the following nosidebar to false and rightsidebar to true. Alternatively, you may write a little script using doconce replace to replace a portion of text in conf.py by a new one:
doconce replace "elif html_theme == 'scipy_lectures': html_theme_options = { 'nosidebar': 'true', 'rightsidebar': 'false', 'sidebarbgcolor': '#f2f2f2', 'sidebartextcolor': '#20435c', 'sidebarlinkcolor': '#20435c', 'footerbgcolor': '#000000', 'relbarbgcolor': '#000000', }" "elif html_theme == 'scipy_lectures': html_theme_options = { 'nosidebar': 'false', 'rightsidebar': 'true', 'sidebarbgcolor': '#f2f2f2', 'sidebartextcolor': '#20435c', 'sidebarlinkcolor': '#20435c', 'footerbgcolor': '#000000', 'relbarbgcolor': '#000000', }" conf.py
Obviously, we could also have changed colors in the edit above. The final alternative is to save the edited conf.py file somewhere and reuse it the next time doconce sphinx_dir is run:
doconce sphinx_dir theme=scipy_lectures \ conf.py=../some/path/conf.py mydoc
If it is not desirable to use the autogenerated scripts explained above, here is the complete manual procedure of generating a Sphinx document from a file mydoc.do.txt.
Step 1. Translate Doconce into the Sphinx format:
Terminal> doconce format sphinx mydoc
Step 2. Create a Sphinx root directory either manually or by using the interactive sphinx-quickstart program. Here is a scripted version of the steps with the latter:
mkdir sphinx-rootdir sphinx-quickstart <<EOF sphinx-rootdir n _ Name of My Sphinx Document Author version version .rst index n y n n n n y n n y y y EOF
The autogenerated conf.py file may need some edits if you want to specific layout (Sphinx themes) of HTML pages. The doconce sphinx_dir generator makes an extended conv.py file where, among other things, several useful Sphinx extensions are included.
Step 3. Copy the mydoc.rst file to the Sphinx root directory:
Terminal> cp mydoc.rst sphinx-rootdir
If you have figures in your document, the relative paths to those will be invalid when you work with mydoc.rst in the sphinx-rootdir directory. Either edit mydoc.rst so that figure file paths are correct, or simply copy your figure directories to sphinx-rootdir. Links to local files in mydoc.rst must be modified to links to files in the _static directory, see comment above.
Step 4. Edit the generated index.rst file so that mydoc.rst is included, i.e., add mydoc to the toctree section so that it becomes:
.. toctree:: :maxdepth: 2 mydoc
(The spaces before mydoc are important!)
Step 5. Generate, for instance, an HTML version of the Sphinx source:
make clean # remove old versions make html
Sphinx can generate a range of different formats: standalone HTML, HTML in separate directories with index.html files, a large single HTML file, JSON files, various help files (the qthelp, HTML, and Devhelp projects), epub, LaTeX, PDF (via LaTeX), pure text, man pages, and Texinfo files.
Step 6. View the result:
Terminal> firefox _build/html/index.html
Note that verbatim code blocks can be typeset in a variety of ways depending the argument that follows !bc: cod gives Python (code-block:: python in Sphinx syntax) and cppcod gives C++, but all such arguments can be customized both for Sphinx and LaTeX output.
There are many different wiki formats, but Doconce only supports three: Googlecode wiki, MediaWiki, and Creole Wiki. These formats are called gwiki, mwiki, and cwiki, respectively. Transformation from Doconce to these formats is done by:
Terminal> doconce format gwiki mydoc.do.txt Terminal> doconce format mwiki mydoc.do.txt Terminal> doconce format cwiki mydoc.do.txt
The produced MediaWiki can be tested in the sandbox of wikibooks.org. The format works well with Wikipedia, Wikibooks, and ShoutWiki, but not always well elsewhere (see this example).
Large MediaWiki documents can be made with the Book creator. From the MediaWiki format one can go to other formats with aid of mwlib. This means that one can easily use Doconce to write Wikibooks and publish these in PDF and MediaWiki format, while at the same time, the book can also be published as a standard LaTeX book, a Sphinx web document, or a collection of HTML files.
The Googlecode wiki document, mydoc.gwiki, is most conveniently stored in a directory which is a clone of the wiki part of the Googlecode project. This is far easier than copying and pasting the entire text into the wiki editor in a web browser.
When the Doconce file contains figures, each figure filename must in the .gwiki file be replaced by a URL where the figure is available. There are instructions in the file for doing this. Usually, one performs this substitution automatically (see next section).
Occasionally, one would like to tweak the output in a certain format from Doconce. One example is figure filenames when transforming Doconce to reStructuredText. Since Doconce does not know if the .rst file is going to be filtered to LaTeX or HTML, it cannot know if .eps or .png is the most appropriate image filename. The solution is to use a text substitution command or code with, e.g., sed, perl, python, or scitools subst, to automatically edit the output file from Doconce. It is then wise to run Doconce and the editing commands from a script to automate all steps in going from Doconce to the final format(s). The make.sh files in docs/manual and docs/tutorial constitute comprehensive examples on how such scripts can be made.
The current text is generated from a Doconce format stored in the file:
doc/tutorial/tutorial.do.txt
The file make.sh in the tutorial directory of the Doconce source code contains a demo of how to produce a variety of formats. The source of this tutorial, tutorial.do.txt is the starting point. Running make.sh and studying the various generated files and comparing them with the original tutorial.do.txt file, gives a quick introduction to how Doconce is used in a real case. Here is a sample of how this tutorial looks in different formats.
There is another demo in the docs/manual directory which translates the more comprehensive documentation, manual.do.txt, to various formats. The make.sh script runs a set of translations.
Below, we explain the manual installation of all software that may be needed when working with Doconce documents. The impatient way to install what is needed is to run the doconce_install_all.sh script.
Doconce itself is pure Python code hosted at http://code.google.com/p/doconce. Its installation from the Mercurial (hg) source follows the standard procedure:
# Doconce hg clone https://code.google.com/p/doconce/ doconce cd doconce sudo python setup.py install cd ..
Since Doconce is frequently updated, it is recommended to use the above procedure and whenever a problem occurs, make sure to update to the most recent version:
cd doconce hg pull hg update sudo python setup.py install
Producing HTML documents, plain text, pandoc-extended Markdown, and wikis can be done without installing any other software. However, if you want other formats as output (LaTeX, Sphinx, reStructuredText) and assisting utilities such as preprocesors, spellcheck, file differences, bibliographies, and so on, the software below must be installed.
If you make use of the Preprocess preprocessor, this program must be installed:
svn checkout http://preprocess.googlecode.com/svn/trunk/ preprocess cd preprocess cd doconce sudo python setup.py install cd ..
A much more advanced alternative to Preprocess is Mako. Its installation is most conveniently done by pip:
pip install Mako
This command requires pip to be installed. On Debian Linux systems, such as Ubuntu, the installation is simply done by:
sudo apt-get install python-pip
Alternatively, one can install from the pip source code.
Mako can also be installed directly from source: download the tarball, pack it out, go to the directory and run the usual sudo python setup.py install.
Different output formats require different formats of image files. For example, PostScript or Encapuslated PostScript is required for latex output, while HTML needs JPEG, GIF, or PNG formats. Doconce calls up programs from the ImageMagick suite for converting image files to a proper format if needed. The ImageMagick suite can be installed on all major platforms. On Debian Linux (including Ubuntu) systems one can simply write:
sudo apt-get install imagemagick
The convenience program doconce combine_images, for combining several images into one, will use montage and convert from ImageMagick and the pdftk, pdfnup, and pdfcrop programs from the texlive-extra-utils Debian package. The latter gets installed by:
sudo apt-get install texlive-extra-utils
Automatic image conversion from EPS to PDF calls up epstopdf, which can be installed by:
sudo apt-get install texlive-font-utils
The utility doconce spellcheck applies the ispell program for spellcheck. On Debian (including Ubuntu) it is installed by:
sudo apt-get install ispell
The Python package Publish is needed if you use a bibliography in your document. On the website, click on Clone, copy the command and run it:
hg clone https://bitbucket.org/logg/publish
Thereafter go to the publish directory and run the setup.py script for installing Publish:
cd publish sudo python setup.py
To make LaTeX documents with very flexible choice of typesetting of verbatim code blocks you need ptex2tex, which is installed by:
svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex cd ptex2tex sudo python setup.py install
It may happen that you need additional style files, you can run a script, cp2texmf.sh:
cd latex sh cp2texmf.sh # copy stylefiles to ~/texmf directory cd ../..
This script copies some special stylefiles that that ptex2tex potentially makes use of. Some more standard stylefiles are also needed. These are installed by:
sudo apt-get install texlive
on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with the necessary stylefiles (if not, they can be found by googling and installed manually in the ~/texmf/tex/latex/misc directory).
Note that the doconce ptex2tex command, which needs no installation beyond Doconce itself, can be used as a simpler alternative to the ptex2tex program.
The minted LaTeX style is offered by ptex2tex and doconce ptext2tex and popular among many users. This style requires the package Pygments to be installed. On Debian Linux:
sudo apt-get install python-pygments
Alternatively, the package can be installed manually:
hg clone<EMAIL_ADDRESS>pygments cd pygments sudo python setup.py install
One can also do the simple:
pip install sphinx
which also installs pygments.
If you use the minted style together with ptex2tex, you have to enable it by the -DMINTED command-line argument to ptex2tex. This is not necessary if you run the alternative doconce ptex2tex program.
All use of the minted style requires the -shell-escape command-line argument when running LaTeX, i.e., latex -shell-escape or pdflatex -shell-escape.
Inline comments apply the todonotes LaTeX package if the ptex2tex or doconce ptex2tex command is run with -DTODONOTES. The todonotes package requires several other packages: xcolor, ifthen, xkeyval, tikz, calc, graphicx, and setspace. The relevant Debian packages for installing all this are listed below.
Many LaTeX packages are potentially needed (depending on various preprocessor variables given to ptex2tex or doconce ptex2tex. The standard packages always included are relsize, epsfig, makeidx, setspace, color, amsmath, amsfonts, xcolor, bm, microtype, titlesec, and hyperref. The ptex2tex package (from ptex2tex) is also included, but removed again if doconce ptex2tex is run instead of the ptex2tex program, meaning that if you do not use ptex2tex, you do not need ptex2tex.sty. Optional packages that might be included are minted, fontspec, xunicode, inputenc, helvet, mathpazo, wrapfig, calc, ifthen, xkeyval, tikz, graphicx, setspace, shadow, disable, todonotes, lineno, xr, framed, mdframe, movie15, a4paper, and a6paper.
Relevant Debian packages that gives you all of these LaTeX packages are:
texlive texlive-extra-utils texlive-latex-extra texlive-font-utils
On old Ubuntu 12.04 one has to do sudo add-apt-repository ppa:texlive-backports/ppa and sudo apt-get update first, or alternatively install these as well:
texlive-math-extra texlive-bibtex-extra texlive-xetex texlive-humanities texlive-pictures
Alternatively, one may pull in texlive-full to get all available style files.
If you want to use the anslistings code environment with ptex2tex (.ptex2tex.cfg styles Python_ANS, Python_ANSt, Cpp_ANS, etc.) or doconce ptex2tex (envir=ans or envir=ans:nt), you need the anslistings.sty file. It can be obtained from the ptex2tex source. It should get installed by the cp2texmf.sh script executed above.
The rst output from Doconce allows further transformation to LaTeX, HTML, XML, OpenOffice, and so on, through the docutils package. The installation of the most recent version can be done by:
svn checkout \ http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils cd docutils sudo python setup.py install cd ..
The command:
pip install sphinx
installs Docutils along with Sphinx and Pygments.
To use the OpenOffice suite you will typically on Debian systems install:
sudo apt-get install unovonv libreoffice libreoffice-dmaths
There is a possibility to create PDF files from reST documents using ReportLab instead of LaTeX. The enabling software is rst2pdf. Either download the tarball or clone the svn repository, go to the rst2pdf directory and run the usual sudo python setup.py install.
Output to sphinx requires of course the Sphinx software, installed by:
hg clone https://bitbucket.org/birkenfeld/sphinx cd sphinx sudo python setup.py install cd ..
An alternative is:
pip install sphinx
Doconce comes with many Sphinx themes that are not part of the standard Sphinx source distribution. Some of these themes require additional Python/Sphinx modules to be installed:
- cloud and redcloud: https://bitbucket.org/ecollins/cloud_sptheme
- bootstrap: https://github.com/ryan-roemer/sphinx-bootstrap-theme
- solarized: https://bitbucket.org/miiton/sphinxjp.themes.solarized
- impressjs: https://github.com/shkumagai/sphinxjp.themes.impressjs
These must be downloaded or cloned, and setup.py must be run as shown above.
The Doconce format pandoc outputs the document in the Pandoc extended Markdown format, which via the pandoc program can be translated to a range of other formats. Installation of Pandoc, written in Haskell, is most easily done by:
sudo apt-get install pandoc
on Debian (Ubuntu) systems.
When the output format is epydoc one needs that program too, installed by:
svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc cd epydoc sudo make install cd ..
Remark. Several of the packages above installed from source code are also available in Debian-based system through the apt-get install command. However, we recommend installation directly from the version control system repository as there might be important updates and bug fixes. For svn directories, go to the directory, run svn update, and then sudo python setup.py install. For Mercurial (hg) directories, go to the directory, run hg pull; hg update, and then sudo python setup.py install.
The doconce diff file1 file prog command for illustrating differences between two files file1 and file2 using the program prog requires prog to be installed. By default, prog is difflib which comes with Python and is always present if you have Doconce installed. Another choice, diff, should be available on all Unix/Linux systems. Other choices, their URL, and their sudo apt-get install command on Debian (Ubuntu) systems appear in the table below.
| Program | URL | Debian/Ubuntu install |
|---|---|---|
| pdiff | a2ps wdiff | sudo apt-get install a2ps wdiff texlive-latex-extra texlive-latex-recommended |
| latexdiff | latexdiff | sudo apt-get install latexdiff |
| kdiff3 | kdiff3 | sudo apt-get install kdiff3 |
| diffuse | diffuse | sudo apt-get install diffuse |
| xxdiff | xxdiff | sudo apt-get install xxdiff |
| meld | meld | sudo apt-get install meld |
| tkdiff.tcl | tkdiff | not in Debian |
On Debian (including Ubuntu) systems, it is straightforward to install the long series of Doconce dependencies:
# Version control systems sudo apt-get install -y mercurial git subversion # Python sudo apt-get install -y idle ipython python-pip python-pdftools texinfo # These lines are only necessary for Ubuntu 12.04 to install texlive 2012 ubuntu_version=`lsb_release -r | awl '{print $2}'` if [ $ubuntu_version = "12.04" ]; then sudo add-apt-repository ppa:texlive-backports/ppa sudo apt-get update fi # LaTeX sudo apt-get install -y texlive texlive-extra-utils texlive-latex-extra texlive-math-extra texlive-font-utils # or sudo apt-get install -y texlive-full # get everything sudo apt-get install -y latexdiff auctex # Image and movie tools sudo apt-get install -y imagemagick netpbm mjpegtools pdftk giftrans gv evince smpeg-plaympeg mplayer totem ffmpeg libav-tools # Misc sudo apt-get install -y ispell pandoc libreoffice unoconv libreoffice-dmaths curl a2ps wdiff meld xxdiff diffpdf kdiff3 diffuse # More Python software pip install sphinx # install pygments and docutils too pip install mako pip install -e svn+http://preprocess.googlecode.com/svn/trunk#egg=preprocess pip install -e hg+https://bitbucket.org/logg/publish#egg=publish pip install -e hg+https://bitbucket.org/ecollins/cloud_sptheme#egg=cloud_sptheme pip install -e git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme pip install -e hg+https://bitbucket.org/miiton/sphinxjp.themes.solarized#egg=sphinxjp.themes.solarized pip install -e git+https://github.com/shkumagai/sphinxjp.themes.impressjs#egg=sphinxjp.themes.impressjs pip install -e svn+https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc#egg=epydoc # Doconce itself rm -rf srclib # put downloaded software in srclib mkdir srclib cd srclib hg clone https://code.google.com/p/doconce/ cd doconce sudo python setup.py install -y cd ../.. # Ptex2tex cd srclib svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex cd ptex2tex sudo python setup.py install -y cd latex sh cp2texmf.sh # copy stylefiles to ~/texmf directory cd ../../..


Land. They ain’t making any more of it, they say.
Nevermind that they are. I’m pretty sure that Singapore and the Netherlands are about half sitting on man-made islands. Weird flat things I know where the water imperceptibly melts off into the land. You can barely tell whether you’re sitting on land or on water. The maps on your phone don’t know either. But, you know, that’s what they say.
Give me land, give me land. If you really care for me, darling, you will give me territory, they say.
That’s another land quote that is always floating around out there. I wish a woman would tell me to give her land. Gosh, I’d probably get married all over again if I ever heard this request. It’s just so. reasonable. I love it. But that’s actually what some people say when they say, “They say…”
The land is the only thing in the world worth working for, worth fighting for, worth dying for, because it’s the only thing that lasts.

Land is a way of life in the American South and has been ever since some royal entrepreneurs came across the pond and started clearing forest and planting crops. They may have got a little lazy there for a bit, but I think at least regarding land they seem to have gotten that right.

Most people probably think that it would be somewhat cheap.
But you know what they say,
Land.
They ain’t makin’ no more!
Posted using Partiko iOS
This page is synchronized from the post: On the Value of Land


5 March 2008
The Ministry of Health and Population of Egypt has announced a new human case of avian influenza A(H5N1) virus infection. The case is an 11-year-old male from Menof District, Menofia Governorate. He was hospitalized with symptoms on 26 February and was confirmed as being infected with A(H5N1) by the Central Public Health Laboratory and NAMRU-3 on 4 March. He remains in a critical condition.
Investigations into the source of his infection indicate a history of contact with sick and dead poultry.
Of the 46 cases confirmed to date in Egypt, 20 have been fatal.


--- layout: post title: "Rush Hour in Utrecht" external-url: http://www.youtube.com/watch?v=n-AbPav5E5M ---
This is my utopia. Amazing what a lack of mandatory helmet laws can do. What are Dutch immigration laws like? Via Kottke.


cat
Print and concatenate files.
More information: home page
- Print the contents of a file to the standard output:
cat path/to/file
- Concatenate several files into an output file:
cat path/to/file1 path/to/file2 ... > path/to/output_file
- Append several files to an output file:
cat path/to/file1 path/to/file2 ... >> path/to/output_file
- Copy the contents of a file into an output file in [u]nbuffered mode:
cat -u /dev/tty12 > /dev/tty13
- Write `stdin` to a file:
cat - > path/to/file
- [n]umber all output lines:
cat -n path/to/file
- Display non-printable and whitespace characters (with `M-` prefix if non-ASCII):
cat -v -t -e path/to/file


Reduce
Energy saving measure |
Progress |
Auto-timed 'switch-off' for the bar heaters in the library |
Complete |
Movement sensor security lights |
Complete |
Hot water system switch |
Complete |
Double window glazing in the children’s room |
Complete |
Air conditioner set for maximum of 20 degrees in winter and a minimum of 27 degrees in summer |
Ongoing educative process |
| Replacement of light globes with energy efficient fluorescent globes |
Complete |
| Replacement of appliances such as stoves & fridges with energy efficient models |
Will be implemented on replacement - as appliance reaches the end of its life |
| Replacement of hot water system with energy efficient gas or solar HWS |
Will be impemented on replacement |
| Installation of draught excluders where required |
We will look at this over this winter |
Potential savings:
- 91.3 kg CO 2 emissions per annum for lighting
- 85.4 kg CO 2 emissions per annum for heating/cooling
- 100-139 kg CO 2 emissions per annum for refrigeration
Reuse
As embodied carbon is frequently the largest carbon impact for an item, Friends have been advised by the carbon footprint auditors to replace items only when they have reached the end of their life, purchase good quality items with a long design life and maintain all appliances assiduously. Where items are disposed prior to the end of their useful life, reuse and recycling should be considered.
Progress: Ongoing educative process.
Recycle
Two rainwater tanks provide water for the Meeting House gardens. Excess rainwater and stormwater from the site will be directed into the large underground water tanks of our neighbours (St Mark's College) who will use this stormwater for irrigating the grounds of the College.
Progress: It is envisaged that the underground tanks and connections will be in place by the end of 2009.
Clean energy and offsets
Measure |
Progress |
| Install a photovoltaic system on the roof of the Library and Children's Room |
Installed 25 May 2009 |
| Tariff change |
Complete - this was a temporary measure to address carbon impacts until those impacts could be addressed by process or infrastructure change. |
| Carbon credits |
Friends are reminded that they can offset their vehicle use, public transport & airline travel emissions by purchasing carbon credits from Quaker Service Australia. |
Back to Adelaide Meeting's photovoltaic index page
Back to Quakers in SA


Working with Static Files¶
By Tom Archer
Static files, which include HTML files, CSS files, image files, and JavaScript files, are assets that the app will serve directly to clients. In this article, we’ll cover the following topics as they relate to ASP.NET 5 and static files.
- In this article:
Serving static files¶
By default, static files are stored in the webroot of your project. The location of the webroot is defined in the project’s project.json
file where the default is wwwroot.
"webroot": "wwwroot"
Static files can be stored in any folder under the webroot and accessed with a relative path to that root. For example, when you create a default Web application project using Visual Studio, there are several folders created within the webroot folder - css
, images
, and js
. In order to directly access an image in the images
subfolder, the URL would look like the following:
http://<yourApp>/images/<imageFileName>
In order for static files to be served, you must configure the Middleware to add static files to the pipeline. This is accomplished by calling the UseStaticFiles
extension method from Startup.Configure
as follows:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Add static files to the request pipeline.
app.UseStaticFiles();
...
Now, let’s say that you have a project hierarchy where the static files you wish to serve are outside the webroot. For example,let’s take a simple layout like the following:
- wwwroot
- css
- images
- ...
- MyStaticFiles
- test.png
In order for the user to access test.png, you can configure the static files middleware as follows:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Add MyStaticFiles static files to the request pipeline.
app.UseStaticFiles(new StaticFileOptions()
{
FileProvider = new PhysicalFileProvider(@"D:\Source\WebApplication1\src\WebApplication1\MyStaticFiles"),
RequestPath = new PathString("/StaticFiles")
});
...
At this point, if the user enters an address of http://<yourApp>/StaticFiles/test.png
, the test.png
image will be served.
Enabling directory browsing¶
Directory browsing allows the user of your Web app to see a list of directories and files within a specified directory (including the root). By default, this functionality is not available such that if the user attempts to display a directory within an ASP.NET Web app, the browser displays an error. To enable directory browsing for your Web app, call the UseDirectoryBrowser
extension method from Startup.Configure
as follows:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Turn on directory browsing for the current directory.
app.UseDirectoryBrowser();
...
The following figure illustrates the results of browsing to the Web app’s images
folder with directory browsing turned on:
Now, let’s say that you have a project hierarchy where you want the user to be able to browse a directory that is not in the webroot. For example, let’s take a simple layout like the following:
- wwwroot
- css
- images
- ...
- MyStaticFiles
In order for the user to browse the MyStaticFiles
directory, you can configure the static files middleware as follows:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Add the ability for the user to browse the MyStaticFiles directory.
app.UseDirectoryBrowser(new DirectoryBrowserptions()
{
FileProvider = new PhysicalFileProvider(@"D:\Source\WebApplication1\src\WebApplication1\MyStaticFiles"),
RequestPath = new PathString("/StaticFiles")
});
...
At this point, if the user enters an address of http://<yourApp>/StaticFiles
, the browser will display the files in the MyStaticFiles
directory.
Serving default files¶
In order for your Web app to serve a default page without the user having to fully qualify the URI, call the UseDefaultFiles
extension method from Startup.Configure
as follows. Note that you must still call UseStaticFiles
as well. This is because UseDefaultFiles
is a URL re-writer that doesn’t actually serve the file. You must still specify middleware (UseStaticFiles
, in this case) to serve the file.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Serve the default file, if present.
app.UseDefaultFiles();
app.UseStaticFiles();
...
If you call the 'UseDefaultFiles
extension method and the user enters a URI of a folder, the middleware will search (in order) for one of the following files. If one of these files is found, that file will be used as if the user had entered the fully qualified URI (although the browser URL will continue to show the URI entered by the user).
- default.htm
- default.html
- index.htm
- index.html
To specify a different default file from the ones listed above, instantiate a DefaultFilesOptions
object and set its DefaultFileNames
string list to a list of names appropriate for your app. Then, call one of the overloaded UseDefaultFiles
methods passing it the DefaultFilesOptions
object. The following example code removes all of the default files from the DefaultFileNames
list and adds mydefault.html
as the only default file for which to search.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Serve my app-specific default file, if present.
DefaultFilesOptions options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("mydefault.html");
app.UseDefaultFiles(options);
app.UseStaticFiles();
...
Now, if the user browses to a directory in the webroot with a file named mydefault.htm
, that file will be served as though the user typed in the fully qualified URI.
But, what if you want to serve a default page from a directory that is outside the webroot directory? You could call both the UseStaticFiles
and UseDefaultFiles
methods passing in identical values for each method’s parameters. However, it’s much more convenient and recommended to call the UseFileServer
method, which is covered in the next section.
Using the UseFileServer method¶
In addition to the UseStaticFiles
, UseDefaultFiles
, and UseDirectoryBrowser
extensions methods, there is also a single method - UseFileServer
- that combines the functionality of all three methods. The following example code shows some common ways to use this method:
// Enable all static file middleware (serving of static files and default files) EXCEPT directory browsing.
app.UseFileServer();
// Enables all static file middleware (serving of static files, default files, and directory browsing).
app.UseFileServer(enableDirectoryBrowsing: true);
As with the UseStaticFiles
, UseDefaultFiles
, and UseDirectoryBrowser
methods, if you wish to serve files that exist outside the webroot, you instantiate and configure an “options” object that you pass as a parameter to UseFileServer
. For example, let’s say you have the following directory hierarchy in your Web app:
- wwwroot
- css
- images
- ...
- MyStaticFiles
- test.png
- default.html
Using the hierarchy example above, you might want to enable static files, default files, and browsing for the MyStaticFiles
directory. In the following code snippet, that is accomplished with a single call to UseFileServer
.
// Enable all static file middleware (serving of static files, default files,
// and directory browsing) for the MyStaticFiles directory.
app.UseFileServer(new FileServerOptions()
{
FileProvider = new PhysicalFileProvider(@"D:\Source\WebApplication1\src\WebApplication1\MyStaticFiles"),
RequestPath = new PathString("/StaticFiles"),
EnableDirectoryBrowsing = true
});
Using the example hierarchy and code snippet from above, here’s what happens if the user browses to various URIs:
http://<yourApp>/StaticFiles/test.png
- TheMyStaticFiles/test.png
file will be served to and presented by the browser.http://<yourApp>/StaticFiles
- Since a default file is present (MyStaticFiles/default.html
), that file will be served. If that file didn’t exist, the browser would present a list of files in theMyStaticFiles
directory (because theFileServerOptions.EnableDirectoryBrowsing
property is set totrue
).
Working with content types¶
The ASP.NET static files middleware defines almost 400 known file content types. If the user attempts to reach a file of an unknown file type, the ASP.NET middleware will not attempt to serve the file.
Let’s take the following directory/file hierarchy example to illustrate:
- wwwroot
- css
- images
- test.image
- ...
Using this hierarchy, you could enable static file serving and directory browsing with the following:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Serve static files and allow directory browsing.
app.UseDirectoryBrowser();
app.UseStaticFiles();
If the user browses to http://<yourApp>/images
, a directory listing will be displayed by the browser that includes the test.image
file. However, if the user clicks on that file, they will see a 404 error - even though the file obviously exists. In order to allow the serving of unknown file types, you could set the StaticFileOptions.ServeUnknownFileTypes
property to true
and specify a default content type via StaticFileOptions.DefaultContentType
. (Refer to this list of common MIME content types.)
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Serve static files and allow directory browsing.
app.UseDirectoryBrowser();
app.UseStaticFiles(new StaticFileOptions
{
ServeUnknownFileTypes = true,
DefaultContentType = "image/png"
});
At this point, if the user browses to a file whose content type is unknown, the browser will treat it as an image and render it accordingly.
So far, you’ve seen how to specify a default content type for any file type that ASP.NET doesn’t recognize. However, what if you have multiple file types that are unknown to ASP.NET? That’s where the FileExtensionContentTypeProvider
class comes in.
The FileExtensionContentTypeProvider
class contains an internal collection that maps file extensions to MIME content types. To specify custom content types, simply instantiate a FileExtensionContentTypeProvider
object and add a mapping to the FileExtensionContentTypeProvider.Mappings
dictionary for each needed file extension/content type. In the following example, the code adds a mapping of the file extension .myapp
to the MIME content type application/x-msdownload
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
// Allow directory browsing.
app.UseDirectoryBrowser();
// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
provider.Mappings.Add(".myapp", "application/x-msdownload");
// Serve static files.
app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
...
Now, if the user attempts to browse to any file with an extension of .myapp
, the user will be prompted to download the file (or it will happen automatically depending on the browser).
IIS Considerations¶
IIS (Internet Information Server) has a native static file module that is independent of the ASP.NET static file middleware components that you’ve learned about in this article. As the ASP.NET modules are run before the IIS native module, they take precedence over the IIS native module. As of ASP.NET Beta 7, the IIS host has changed so that requests that are not handled by ASP.NET will return empty 404 responses instead of allowing the IIS native modules to run. To opt into running the IIS native modules, add the following call to the end of Startup.Configure
.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
...
...
// Enable the IIS native module to run after the ASP.NET middleware components.
// This call should be placed at the end of your Startup.Configure method so that
// it doesn't interfere with other middleware functionality.
app.RunIISPipeline();
}
Best practices¶
This section includes a list of best practices for working with static files:
- Code files (including C# and Razor files) should be placed outside of the app project’s webroot. This creates a clean separation between your app’s static (non-compilable) content and source code.
Summary¶
In this article, you learned how the static files middleware component in ASP.NET 5 allows you to serve static files, enable directory browsing, and serve default files. You also saw how to work with content types that ASP.NET doesn’t recognize. Finally, the article explained some IIS considerations and presented some best practices for working with static files.