diff options
Diffstat (limited to 'macros/latex/contrib/morehype/docsrc/blog.tex')
-rw-r--r-- | macros/latex/contrib/morehype/docsrc/blog.tex | 477 |
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 +/- |