[tex4ht-commits] [SCM] tex4ht updated: r354 - trunk/doc/tex4ht-doc

[michal_h21 at gnu.org.ua]

Author: michal_h21
Date: 2017-12-08 15:00:52 +0200 (Fri, 08 Dec 2017)
New Revision: 354

Added:
   trunk/doc/tex4ht-doc/style.css
Modified:
   trunk/doc/tex4ht-doc/Makefile
   trunk/doc/tex4ht-doc/config.cfg
   trunk/doc/tex4ht-doc/tex4ht-doc.tex
   trunk/doc/tex4ht-doc/tex4ht-styles.sty
Log:
Added basic info about new package support

Modified: trunk/doc/tex4ht-doc/Makefile
===================================================================
--- trunk/doc/tex4ht-doc/Makefile	2017-12-08 09:11:50 UTC (rev 353)
+++ trunk/doc/tex4ht-doc/Makefile	2017-12-08 13:00:52 UTC (rev 354)
@@ -13,10 +13,10 @@
 
 .PHONY: final
 
-tex4ht-doc.pdf: tex4ht-doc.tex
+tex4ht-doc.pdf: tex4ht-doc.tex tex4ht-styles.sty
 	lualatex tex4ht-doc.tex
 
-tex4ht-doc.html: tex4ht-doc.tex config.cfg
+tex4ht-doc.html: tex4ht-doc.tex config.cfg tex4ht-styles.sty
 	make4ht -um $(mode) -c config $(engine) -e build.mk4  tex4ht-doc.tex
 
 # use only one LaTeX run by default, request three compilations with final rule

Modified: trunk/doc/tex4ht-doc/config.cfg
===================================================================
--- trunk/doc/tex4ht-doc/config.cfg	2017-12-08 09:11:50 UTC (rev 353)
+++ trunk/doc/tex4ht-doc/config.cfg	2017-12-08 13:00:52 UTC (rev 354)
@@ -1,3 +1,8 @@
-\Preamble{xhtml,html5,mathml,2,sec-filename,info}
+\Preamble{xhtml,html5,mathml,2,sec-filename,info,fn-in}
+\special{t4ht+ at File: style.css}
+\Configure{@HEAD}{\HCode{<link rel="stylesheet" type="text/css" href="style.css">}}
+\Configure{texttt}{\HCode{<code>}\NoFonts}{\EndNoFonts\HCode{</code>}}
+\ConfigureEnv{texsource}{\ifvmode\IgnorePar\fi\HCode{<code>}}{\HCode{</code>}}{}{}
+
 \begin{document}
 \EndPreamble

Modified: trunk/doc/tex4ht-doc/tex4ht-doc.tex
===================================================================
--- trunk/doc/tex4ht-doc/tex4ht-doc.tex	2017-12-08 09:11:50 UTC (rev 353)
+++ trunk/doc/tex4ht-doc/tex4ht-doc.tex	2017-12-08 13:00:52 UTC (rev 354)
@@ -1,5 +1,7 @@
 \documentclass{book}
 \usepackage{url}
+\usepackage{xcolor}
+\usepackage{tex4ht-styles}
 
 \usepackage{glossaries}
 \title{TeX4ht Documentation}
@@ -71,8 +73,77 @@
 
 \subsection{Configure the hooks in output format configuration files}
 
+\section{How to add support for a package to the \texfourht\ literate sources}
 
+To add a proper support for a new package, it is necessary to edit the 
+\texfourht\ literate sources. The configurable hooks need to be placed in the \file{tex4ht-4ht.tex},
+the configuration of these hooks must be added to the output format configuration files.
+The most common output format is \HTML, which can be configured in \file{tex4ht-html4.tex}, or 
+\file{tex4ht-html5.tex} if \HTMLV\ features are used. It is also necessary to update the
+\file{mktex4ht-cnf.tex}.
 
+\subsection{Example}
+
+Given following package \file{sample.sty}:
+
+\begin{texsource}
+\ProvidesPackage{sample}
+\newcommand\hello{world}
+\endinput
+\end{texsource}
+
+This simple package defines command \texcommand{\hello}, which simply prints the word \textit{hello} when used in a document.
+
+Let's say that we want to insert some \HTML\ tags before and after the text content printed by the command.
+
+Basic template for \file{tex4ht-4ht.tex}
+
+\begin{texsource}
+\<sample.4ht\><<<
+% sample.4ht (|version), generated from |jobname.tex
+% Copyright 2017 TeX Users Group
+|<TeX4ht license text|>
+
+\NewConfigure{hello}{2}
+\pend:def\hello{\a:hello}
+\append:def\hello{\b:hello}
+\Hinput{sample}
+>>> \AddFile{9}{sample}
+\end{texsource}
+
+Configuration for each package must follow this basic template. The \ProTeX\ system is used as system for literate programming.
+
+The \texcommand{\<name\><<<code>>>} block defines new macro which can be then called using \texcommand{|<name|>}. The license text
+is included in the example this way. In order to generate the \file{sample.4ht} file, we need to use \texttt{sample.4ht} as a name
+in the code block and command \texcommand{\AddFile{9}{sample}} after the block definition\footnote{I have no idea what the number
+in the first parameter means.}.
+
+Each package configuration  must include \texcommand{\Hinput{packagename}}, in order to load the configurations for the package.
+
+The command \texcommand{\NewConfigure{hello}{2}} declares new configuration \texttt{hello}, with two configurable hooks. 
+These hooks are named  \texcommand{\a:hello} and \texcommand{\b:hello}. The hooks must be inserted into the 
+\texcommand{\hello}, which can be easily done using the \texcommand{\pend:def} and \texcommand{\append:def} commands. These
+commands can insert code  at the beginning, respective at the end of the redefined command.
+
+The configuration for \HTML\ must be placed in the \file{tex4ht-html4.tex} file:
+
+\begin{texsource}
+\<configure html4 sample\><<<
+\Configure{hello}{\HCode{<span class="hello">}}{\HCode{</span>}}
+\Css{.hello{color:red;}}
+>>>
+\end{texsource}
+
+The configuration for a package must be placed in \texcommand{\<configure html4 packagename\>} block.
+
+
+
+The package name must be also included in \file{mktex4ht-cnf.tex}:
+
+\begin{texsource}
+\AddFile{9}{sample}
+\end{texsource}
+
 \chapter{Glossary}
 \chapter{Bibliography}
 \chapter{Index}

Modified: trunk/doc/tex4ht-doc/tex4ht-styles.sty
===================================================================
--- trunk/doc/tex4ht-doc/tex4ht-styles.sty	2017-12-08 09:11:50 UTC (rev 353)
+++ trunk/doc/tex4ht-doc/tex4ht-styles.sty	2017-12-08 13:00:52 UTC (rev 354)
@@ -1,3 +1,22 @@
 \ProvidesPackage{tex4ht-styles}
+\RequirePackage{listings}
+\RequirePackage{xparse}
 
+% shortcuts 
+\newcommand\texfourht{\texttt{tex4ht}}
+\newcommand\HTML{\texttt{HTML}}
+\newcommand\HTMLV{\texttt{HTML5}}
+\newcommand\ProTeX{\texttt{ProTeX}}
+
+
+% formatting commands
+\newcommand\file[1]{\texttt{#1}}
+
+% this trick will enable us to take verbatim arguments
+% https://tex.stackexchange.com/a/45292/2891
+\NewDocumentCommand\texcommand{v}{\texttt{#1}}
+
+\lstnewenvironment{texsource}{\lstset{language=TeX}}{}
+\newcommand\texinput[1]{\lstinputlisting[language=TeX]{#1}}
+
 \endinput