\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 `[[]]' 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{}| \ starts a slide whose content is aligned flush left, \cmdboxitem|\nextcenterscreenpage{}| \ 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{}| where may be arbitrary, or `START' may be a fine choice for . Finally, there are user commands for \strong{centering} slide content horizontically (cf.~Sec.~\ref{sec:dot-type}): \begin{description} \cmdboxitem|\cheading{}{}| \ ``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 +/-