path: root/macros/latex/contrib/morehype/docsrc/blog.tex

\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 +/-