summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/morehype/docsrc/blog.tex
blob: 712eeeb986e095c5c0ae95952e43d579d8c9d095 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
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 +/-