summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/morehype/docsrc/blog.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/morehype/docsrc/blog.tex')
-rw-r--r--macros/latex/contrib/morehype/docsrc/blog.tex477
1 files changed, 477 insertions, 0 deletions
diff --git a/macros/latex/contrib/morehype/docsrc/blog.tex b/macros/latex/contrib/morehype/docsrc/blog.tex
new file mode 100644
index 0000000000..712eeeb986
--- /dev/null
+++ b/macros/latex/contrib/morehype/docsrc/blog.tex
@@ -0,0 +1,477 @@
+\ProvidesFile{blog.tex}[2013/01/04 documenting blog.sty]
+\title{\textsf{blog.sty}\\---\\%
+ Generating \HTML\ Quickly with \TeX\thanks{This
+ document describes version
+ \textcolor{blue}{\UseVersionOf{\jobname.sty}}
+ of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
+% \listfiles
+{ \RequirePackage{makedoc}
+ \ProcessLineMessage{}
+ %% three section levels 2012/08/07:
+ \renewcommand\mdSectionLevelOne {\string\subsection}
+ \renewcommand\mdSectionLevelTwo {\string\subsubsection}
+ \renewcommand\mdSectionLevelThree{\string\paragraph}
+ \MainDocParser{\SectionLevelThreeParseInput}
+ \HeaderLines{16} %% 2012/10/03
+ \MakeSingleDoc{blog.sty}
+ \HeaderLines{18} %% 2012/11/28
+ \MakeSingleDoc{blogligs.sty}
+ \HeaderLines{18} %% 2012/11/28
+ \MakeSingleDoc{markblog.sty}
+ \HeaderLines{18} %% 2012/10/05
+ \MakeSingleDoc{lnavicol.sty}
+ \HeaderLines{17} %% 2012/10/05
+ \MakeSingleDoc{blogdot.sty}
+}
+\documentclass[fleqn]{article}%% TODO paper dimensions!?
+\sfcode`-=1001 %% 2011/10/15
+\input{makedoc.cfg} %% shared formatting settings
+\usepackage{filesdo} \MDfinaldatechecks %% 2012/12/20
+\ReadPackageInfos{blog}
+ %% \tagcode seems to be a quite recent pdfTeX primitive,
+ %% cf. microtype.pdf ... %% 2010/11/06
+\newcommand*{\xmltagcode}[1]{\texttt{<#1>}}
+\newcommand*{\HTML}{\acro{HTML}} %% 2011/09/08
+\newcommand*{\CSS}{\acro{CSS}} %% 2011/11/09
+\newcommand*{\secref}[1]{Sec.~\ref{sec:#1}} %% 2011/11/23
+\providecommand*{\LuaTeX}{Lua\TeX} %% 2012/12/20
+\sloppy
+\begin{document}
+\maketitle
+\begin{abstract}\noindent
+'blog.sty' provides \TeX\ macros for generating web pages,
+based on processing text files using the 'fifinddo' package.
+Some \LaTeX\
+commands %%% command names
+are redefined to access their \HTML\
+equivalents, other new macro names ``quote" the names of \HTML\ elements.
+The package has evolved in several little steps
+each aiming at getting pretty-looking ``hypertext" \textbf{notes}
+with little effort,
+where ``little effort" also has meant avoiding studying
+documentation of similar packages already existing.
+[\textcolor{blue}{TODO:} list them!]
+% Version v0.3 is the remainder of v0.2 after moving some stuff
+% to 'fifinddo.sty' (especially `\CopyFile');
+% moreover, the new `\BlogCopyFile' replaces empty source lines
+% by \HTML's \xmltagcode{p} (starting a new paragraph).---Real
+% \emph{typesetting} from the same `.tex' source
+% (pretty printable output) has not been tried yet.
+%% <- 2011/01/24 ->
+The package %%% rather
+\emph{``misuses"} \TeX's macro language
+for generating \HTML\ code and entirely \emph{ignores}
+\TeX's typesetting capabilities.%%%---What about
+% such a ``small" \TeX\ with macros only and
+% \emph{no} typesetting capabilities ...!?
+---'lnavicol.sty' adds a more \strong{professional} look
+(towards CMS?), and 'blogdot.sty' uses 'blog.sty'
+for \HTML\ \strong{beamer} presentations.
+\end{abstract}
+\tableofcontents
+
+\section{Installing and Usage}
+The file 'blog.sty' is provided ready,
+\strong{installation} only requires
+putting it somewhere where \TeX\ finds it
+(which may need updating the filename data
+ base).\urlfoot{ukfaqref}{inst-wlcf}
+
+\strong{User commands} are described near their implementation below.
+
+However, we must present an \strong{outline} of the procedure
+for generating \HTML\ files:
+
+At least one \strong{driver} file and one \strong{source} file are
+needed.
+
+The \strong{driver} file's name is stored in `\jobname'.
+It loads 'blog.sty' by
+\begin{verbatim}
+ \RequirePackage{blog}
+\end{verbatim}
+and uses file handling commands from 'blog.sty' and
+\CtanPkgRef{nicetext}{fifinddo}
+(cf. `mdoccheat.pdf' from the \ctanpkgref{nicetext} bundle).\urlfoot{CtanPkgRef}{nicetext}
+%% <- \urlfoot 2012/11/30
+It chooses \strong{source} files and the name(s) for the resulting
+\HTML\ file(s). It may also need to load local settings, such as
+%% 2012/11/29:
+`\uselangcode' with the \ctanpkgdref{langcode} package %% dref 2012/11/30
+and settings for converting the editor's text encoding
+into the encoding that the head of the resulting \HTML\ file
+advertises---or into \HTML\ named entities
+(for me, `atari_ht.fdf' has done this).
+
+The driver file could be run a terminal dialogue in order to choose source
+and target files and settings. So far, I rather have programmed a
+dialogue just for converting UTF-8 into an encoding that my
+Atari editor \textsc{xEDIT} can deal with.
+I do not present this now because it was conceptually mistaken,
+I must set up this conversion from scratch some time.
+% [TODO: present in 'nicetext']. %% 2011/01/24
+
+The \strong{source} file(s) should contain user commands defined below
+to generate the necessary \xmltagcode{head} section and the
+\xmltagcode{body} tags.
+
+\section{Examples}
+\subsection{Hello World!}
+This is the \strong{source} code for a ``Hello World" example,
+in `hellowor.tex':
+\MDsamplecodeinput{hellowor}
+The \HTML\ file `hellowor.htm' is generated from `hellowor.tex'
+by the following \strong{driver} file `mkhellow.tex':
+\pagebreak[2]
+\MDsamplecodeinput{mkhellow}
+
+ \iffalse %% 2012/11/29
+\subsection{A Very Plain Style}
+My ``\TeX-generated
+pages"{\foothttpurlref{www.webdesign-bu.de/%
+ uwe\string_lueck/texmap.htm}}
+use a \strong{driver} file `makehtml.tex'.
+To choose a page to generate, I ``uncomment"ed just one
+of several lines that set the ``current conversion job"
+from a list (for some time).
+I choose the example of a simple ``site map:"
+`texmap.htm' is generated from \strong{source} file
+`texmap.tex'.---More recently however, I have started to
+read the job name and perhaps extra settings from a file
+`jobname.tex' that is created by a Bash script.
+
+In order to make it easier for the reader to see what is essential,
+I~have moved many `.cfg'-like extra definitions into a file
+`texblog.fdf'. Some of these definitions may later move into
+`blog.sty'. You should find `makehtml.tex', `texmap.tex', and
+`texblog.fdf' in a directory `demo/texblog'
+(or `texblog.fdf' may be together with the `.sty' files),
+perhaps you can use them as templates.
+
+\begingroup
+ \MakeOther\|
+% \MakeOther\`\MakeOther\' %% disables \tt! 2011/09/08
+ \MakeOther\<
+ \MakeActive\ \def{\"o} %% 2011/10/10
+ \MakeActive\ \def{\"u}
+ \hfuzz=\textwidth \advance \hfuzz by 28pt
+\subsubsection{Driver File `makehtml.tex'}
+ %% <- TODO \file needs protection for PDF 2011/09/08
+ \enlargethispage{1\baselineskip}
+ \listinginput[5]{1}{CTAN/morehype/demo/texblog/makehtml.tex}
+\subsubsection{Source File \texttt{texmap.tex}}
+ \listinginput[5]{1}{CTAN/morehype/demo/texblog/texmap.tex}
+\endgroup
+
+ \fi
+\subsection{A Style with a Navigation Column}
+\label{sec:example-lnavicol}
+A style of web pages looking more professional
+% than %% rm. 2012/11/29
+% `texmap.htm' %% was `texhax.hmt' 2011/09/02
+(while perhaps becoming outdated) has a small navigation column
+on the left, side by side with a column for the main content.
+Both columns are spanned by a header section above and a footer
+section below. The package 'lnavicol.sty' provides commands
+`\PAGEHEAD', `\PAGENAVI', `\PAGEMAIN', `\PAGEFOOT', `\PAGEEND'
+(and some more) for structuring the source so that the code
+following `\PAGEHEAD' generates the header, the code following
+`\PAGENAVI' forms the content of the navigation column, etc.
+Its code is presented in Sec.~\ref{sec:lnavicol}.
+For real professionality, somebody must add some fine \acro{CSS},
+and the macros mentioned may need to be redefined to use the `@class'
+attribute. Also, I am not sure about the table macros in 'blog.sty',
+so much may change later.
+
+With things like these, can 'blog.sty' become a part of a
+``\Wikienref{content management system}" for \TeX\ addicts?
+This idea rather is based on the
+\wikideref{Content Management System}{\meta{German}}
+Wikipedia article.
+
+As an example, I present parts of the source for my
+``home page"{\foothttpurlref{www.webdesign-bu.de/%
+ uwe\string_lueck/schreibt.html}}.
+As the footer is the same on all pages of this style,
+it is added in the driver file `makehtml.tex'.
+`schreibt.tex' is the source file for generating `schreibt.html'.
+You should find \emph{this} `makehtml.tex', a cut down version of
+`schreibt.tex', and `writings.fdf' with my extra macros for these pages
+in a directory
+`blogdemo/writings', %% blog 2012/11/30
+hopefully useful as templates.
+
+\begingroup
+ \MakeActive\ \def{\"a} %% 2011/10/05
+ \MakeActive\ \def{\"u}
+ \hfuzz=\textwidth \advance \hfuzz by 10pt
+ %% 2012/11/29 CTAN/morehype/demo -> blogdemo:
+\subsubsection{Driver File `makehtml.tex'}
+ \listinginput[5]{1}{blogdemo/writings/makehtml.tex}
+\subsubsection{Source File `schreibt.tex'}
+ \listinginput[5]{1}{blogdemo/writings/schreibt.tex}
+\endgroup
+
+\pagebreak %% 2013/01/04
+\section{The File \file{blog.sty}} %% 2011/11/09
+% \section{The File \texttt{blog.sty}}
+% \section{The File {\tt blog.sty}}
+%% <- strange 2011/11/08 ->
+% \section{The File `blog.sty'} %% 2011/10/04 allow other files
+\subsection{Preliminaries} %% 2012/10/03
+\subsubsection{Package File Header (Legalese)} %% ize -> ese, subsub 2012/10/03
+\ResetCodeLineNumbers
+\input{blog.doc}
+
+\section{``Pervasive Ligatures" with 'blogligs.sty'} %% 2012/11/29
+\label{sec:moreligs}
+% \AddQuotes
+This is the code and documentation of the package mentioned in
+Sec.~\ref{sec:ligs}, loadable by option |[ligs]|.
+See below for what is offered.
+\ResetCodeLineNumbers
+\input{blogligs.doc}
+% \DontAddQuotes
+
+\section{Wiki Markup by 'markblog.sty'} %% 2012/11/29
+\label{sec:mark}
+\subsection{Introduction} %% 2012/12/20
+\AddQuotes
+This is the code and documentation of the package mentioned in
+Sec.~\ref{sec:ligs}, loadable by option |[mark]|.
+See below for what is offered. You should also find a file
+`markblog.htm' that sketches it. Moreover, `texlinks.pdf'
+describes in detail to what extent Wikipedia's
+``\wikiref{Help:Links#Piped_links}{piped links}"
+with `[[<wikipedia-link>]]' is supported. %% <...> 2012/12/20
+
+\subsection{Similar Packages} %% 2012/12/20
+'wiki.sty' from the \ctanpkgdref{nicetext} bundle has offered
+some Wikipedia-like markup as a front-end for ordinary
+typesetting with \LaTeX\ (for \acro{DVI}/\acro{PDF}),
+implemented in a way very different from what is going on here,
+rather converting markup sequences \emph{during} typesetting.
+
+More similar to the present approach is the way how
+Wikipedia section titles in package documentation
+is implemented by 'makedoc' from the 'nicetext' bundle,
+based on \strong{preprocessing} by 'fifinddo'.
+
+In general, John MacFarlane's
+\httpref{johnmacfarlane.net/pandoc}{\pkg{pandoc}}
+(cf.~\wikideref{pandoc}{German Wikipedia})
+converts between wiki-like (simplified) markup and
+\LaTeX\ markup. (It deals with rather fixed
+markup rules, while we here process markup sequences
+independently of an entire markup \emph{language}.)
+
+Another straightforward and well-documented way to
+\emph{preprocess} source files for converting simplified
+markup into \TeX\ markup is \ctanpkgauref{isambert}{Paul Isambert}'s
+\ctanpkgref{interpreter}. It relies on \wikiref{LuaTeX}{\LuaTeX}
+where Lua does the preprocessing.
+
+\subsection{Package File Header} %% 2012/12/20
+\ResetCodeLineNumbers
+\input{markblog.doc}
+\DontAddQuotes
+
+%% rm. \pagebreak 2013/01/04
+\section{Real Web Pages with 'lnavicol.sty'}
+\label{sec:lnavicol}
+This is the code and documentation of the package mentioned in
+Sec.~\ref{sec:example-lnavicol}.
+\ResetCodeLineNumbers
+\input{lnavicol.doc}
+
+\section{Beamer Presentations with 'blogdot.sty'}
+\subsection{Overview}
+'blogdot.sty' extends 'blog.sty' in order to construct ``\HTML\
+slides." One ``slide" is a 3$\times$3 table such that
+\begin{enumerate}
+ \item it \strong{fills} the computer \strong{screen},
+ \item the center cell is the \strong{``type area,"}
+ \item the ``margin cell" below the center cell
+ is a \strong{link} to the \strong{next} ``slide,"
+ \item the lower right-hand cell is a \strong{``restart"} link.
+\end{enumerate}
+Six \strong{size parameters} listed in Sec.~\ref{sec:dot-size}
+must be adjusted to the screen in `blogdot.cfg'
+(or in a file with project-specific definitions).
+
+We deliver a file |blogdot.css| containing \strong{\acro{CSS}} font size
+declarations that have been used so far; you may find better ones
+or ones that work better with your screen size, or you may need to add
+style declarations for additional \HTML\ elements.
+
+Another parameter that the user may want to modify is the
+\strong{``restart" anchor name} |\BlogDotRestart|
+(see Sec.~\ref{sec:dot-fin}).
+Its default value is |START| for the ``slide" opened by the command
+|\titlescreenpage| that is defined in Sec.~\ref{sec:dot-start}.
+
+That slide is meant to be the ``\strong{title} slide"
+of the presentation. In order to \strong{display} it,
+I recommend to make and use a \strong{link} to |START| somewhere
+(such as with 'blog.sty''s `\ancref' command).
+The \emph{content} of the title slide is \emph{centered} horizontically,
+so certain commands mentioned \emph{below}
+(centering on other slides) may be useful.
+
+\emph{After} `\titlescreenpage', the next main \strong{user commands}
+are
+\begin{description}
+ \cmdboxitem|\nextnormalscreenpage{<anchor-name>}| \
+ starts a slide whose content is aligned flush left,
+ \cmdboxitem|\nextcenterscreenpage{<anchor-name>}| \
+ starts a slide whose content is centered horizontally.
+\end{description}
+---cf.~Sec.~\ref{sec:dot-next}. Right after these commands,
+as well as right after `\title'\-`screen`\-'page', code is used to
+generate the content of the \strong{type area} of the corresponding
+slide. Another `\next...' command closes that content and opens
+another slide. The presentation (the content of the very last slide)
+may be finished using |\screenbottom{<final>}| where <final> may be
+arbitrary, or `START' may be a fine choice for <final>.
+
+Finally, there are user commands for \strong{centering} slide content
+horizontically (cf.~Sec.~\ref{sec:dot-type}):
+\begin{description}
+ \cmdboxitem|\cheading{<digit>}{<title>}| \
+ ``printing" a heading centered horizontically---even on slides
+ whose remaining content is aligned \emph{flush left}
+ (I have only used <digit>=2 so far),
+ \cmdboxitem|\begin{textblock}{<width>}| \ %% not metavar 2012/07/19
+ ``printing" the content of a `{textblock}' environment with
+ maximum line width <width> flush left,
+ while that ``block" as a whole may be centered
+ horizontically on the slide due to choosing
+ `\nextcenterscreenpage'---especially for \strong{list}
+ environments with entry lines that are shorter than the
+ type area width and thus would not look centered
+ (below a centered heading from `\cheading').
+\end{description}
+
+The so far single \strong{example} of a presentation prepared using 'blogdot'
+is \ctanfileref{info/fifinddo-info}{dantev45.htm}
+%% <- 2011/10/21 ->
+(\ctanpkgref{fifinddo-info} bundle),
+a sketch of applying 'fifinddo' to package
+documentation and \HTML\ generation. A ``driver" file is needed
+for generating the \HTML\ code for the presentation from a `.tex'
+source by analogy to generating any \HTML\ file using 'blog.sty'.
+For the latter purpose, I have named my driver files `makehtml.tex'.
+For `dantev45.htm', I have called that file |makedot.tex|,
+the main difference to `makehtml.tex' is loading `blogdot.sty'
+in place of `blog.sty'.
+
+This example also uses a file `dantev45.fdf' that defines some
+commands that may be more appropriate as user-level commands
+than the ones presented here (which may appear to be still too
+low-level-like):
+\begin{description}
+ \cmdboxitem|\teilpage{<number>}{<title>}|
+ making a ``cover slide" for announcing a new ``part"
+ of the presentation in German,
+ \cmdboxitem|\labelsection{<label>}{<title>}|
+ starting a slide with heading <title>
+ and with anchor <label>
+ (that is displayed on clicking a \emph{link} to
+ <label>)---using
+ \[`\nextnormalscreenpage{<label>}'\mbox{ and }
+ `\cheading2{<title>}',\]
+ \cmdboxitem|\labelcentersection{<label>}{<title>}|
+ like the previous command except that the slide content will be
+ \emph{centered} horizontally, using
+ \[`\nextcenterscreenpage{<title>}'.\]
+\end{description}
+
+%% 2011/10/10:
+\strong{Reasons} to make \HTML\ presentations may be:\ \
+(i)~As opposed to office software, this is a transparent light-weight
+approach.\ \
+Considering \emph{typesetting} slides with \TeX,\ \
+(ii)~\TeX's advanced typesetting abilities such as automatical
+page breaking are not very relevant for slides;\ \
+(iii)~a typesetting run needs a second or a few seconds,
+while generating \HTML\ with 'blog.sty' needs a fraction of a second;\ \
+(iv)~adjusting formatting parameters such as sizes and colours
+needed for slides is somewhat more straightforward with \HTML\
+than with \TeX.
+
+%% 2011/10/11, 2011/10/15:
+\strong{Limitations:} \
+First I was happy about how it worked on my netbook,
+but then I realized how difficult it is to present the ``slides" ``online."
+Screen sizes (centering) are one problem.
+(Without the ``restart" idea, this might be much easier.)
+Another problem is that the ``hidden links" don't work with
+\Wikienref{Internet Explorer} as they work with
+\Wikienref{Firefox}, \Wikienref{Google Chrome}, and
+\Wikiendisambref{Opera}{web browser}.
+% I am now working at an easy choice of ``recompiling options."
+And finally, in internet shops some
+\HTML\ entities/symbols were not supported.
+In any case I (again) became aware of the fact
+that \HTML\ is not as \strong{``portable"} as \acro{PDF}.
+
+Some \strong{workarounds} are described in Sec.~\ref{sec:cfgs}.
+|\FillBlogDotTypeArea| has two effects: \ (i)~providing an additional
+link to the \emph{next} slide for MSIE, \ (ii)~\emph{widening}
+and centering the \emph{type area} on larger screens
+than the one which the presentation originally was made for. \
+An optional argument of |\TryBlogDotCFG| is offered for a `.cfg' file
+overriding the original settings for the presentation.
+Using it, I learnt that for ``portability," some manual line breaks
+(`\\', \xmltagcode{br}) should be replaced by ``ties" between the
+words \emph{after} the intended line break
+(when the line break is too ugly in a wider type area).
+For keeping the original type area width on wider screens
+(for certain ``slides", perhaps when line breaks really are wanted
+ to be preserved), the |{textblock}| environment may be used.
+Better \HTML\ and \acro{CSS} expertise may eventually
+lead to better solutions.
+
+The \strong{name} \qtd{blogdot} is a ``pun" on the name of the
+\ctanpkgref{powerdot} package (which in turn refers to
+``\Wikienref{PowerPoint}").
+
+\subsection{File Header}
+\ResetCodeLineNumbers
+\input{blogdot.doc}
+
+\end{document}
+
+HISTORY
+
+2010/11/05 for v0.2
+2010/11/11 for v0.3
+2011/01/23 using readprov and color
+2011/01/27 using \urlfoot
+2011/09/01 using new makedoc.cfg incl. \acro and \foothttp...;
+ extension for twocolpg.sty
+with morehype RELEASE r0.4
+2011/09/02 twocolpg.sty renamed into lnavicol.sty, typo fixes
+2011/09/08 \HTML
+2011/09/23 TODO in abstract blue again
+2011/10/05 umlaut-a in schreibt.tex
+2011/10/07f. blogdot
+2011/10/09 lnavicol
+2011/10/10 tuning; reasons for blogdot
+2011/10/11 limitations of blogdot, corrected makedoc code
+2011/10/15 more on limitations of blogdot;
+ abstract on lnavicol and blogdot
+2011/10/21 links to fifinddo-info/dantev45.htm
+2011/11/05 using \MakeSingleDoc from makedoc.sty v0.42
+2011/11/08 playing with alternatives to defective `blog.sty'
+ in page head
+2011/11/09 so use \file with new makedoc.cfg for hyperref; \CSS
+2011/11/23 \secref
+2012/07/19 `textblock' not metavar
+2012/08/07 three section levels
+2012/10/03 ize -> ese, some restructuring, corr. \HeaderLines
+2012/10/05 adjusted \HeaderLines (differ!)
+2012/11/29 adding `blogligs' and `markblog'
+2012/11/30 hello world, texblog sample removed, url foots
+2012/12/20 filedate checks, doc. more about `markblog'
+2013/01/04 \pagebreak +/-