doc: EHC structure paper adapted as to allow it to be a 'live', evolv…

…ing document

Makefile

@@ -58,8 +58,10 @@ include $(SRC_PREFIX)agprimer/files.mk
 -include $(SRC_PREFIX)infer2pass/files.mk
 -include figs/files.mk
 -include text/files1.mk
+-include text/files-variantts.mk
 -include $(wildcard text/files1-*.mk)
 -include text/files2.mk
+-include text/files-targets.mk
 -include $(wildcard text/files2-*.mk)
 -include www/files.mk
 include ehclib/files.mk

src/text2text/Text/AbsSyn.ag

@@ -50,6 +50,7 @@ DATA TextItem
   						str				: {String}
   | BreakLine
   | HorRuler
+  | TableHorRuler
 
   -- pictures
   | GraphicsInline		mboptions		: MbGraphicsInlineOptions

src/text2text/Text/Parser/DocLaTeX.hs

@@ -27,8 +27,18 @@ cmd0argMp
   = Map.fromList
       [ ("maketitle"        , TextItem_MakeTitle        )
       , ("tableofcontents"  , TextItem_TOC              )
-      , ("hline"            , TextItem_HorRuler         )
-      -- , ("\\"                , TextItem_BreakLine        )
+      ]
+
+cmdPlain0argMp :: Map.Map String TextItem
+cmdPlain0argMp
+  = Map.fromList
+      [ ("hline"            , TextItem_HorRuler         )
+      ]
+
+cmdTable0argMp :: Map.Map String TextItem
+cmdTable0argMp
+  = Map.fromList
+      [ ("hline"            , TextItem_TableHorRuler         )
       ]
 
 -------------------------------------------------------------------------
@@ -47,9 +57,12 @@ cmd1argMp
       , ("emph"                 , TextItem_Styled TextStyle_Emphasized      )
       , ("usepackage"           , TextItem_Import                           )
       , ("paragraph"            , TextItem_Header HeaderLevel_Paragraph     )
+      , ("secRef"     			, mkref1 "section"							)
+      , ("figRef"     			, mkref1 "figure"							)
       -- , ("includegraphics"      , TextItem_GraphicsInline Nothing           )
       ]
     `Map.union` Map.fromList [ (concat (replicate l "sub") ++ "section", TextItem_Header (HeaderLevel_Level l)) | l <- [0..2] ]
+  where mkref1 t l = TextItem_RefTo RefType_Local l [TextItem_NonSpace t]
 
 -------------------------------------------------------------------------
 -- 2 arg cmds
@@ -156,6 +169,8 @@ doclatexScanOpts
       , scoCommandsTxt      =   Set.fromList [ "begin", "end", "item", "documentclass", "includegraphics" ]
                                 -- `Set.union` Map.keysSet textstyleMp
                                 `Set.union` Map.keysSet cmd0argMp
+                                `Set.union` Map.keysSet cmdPlain0argMp
+                                `Set.union` Map.keysSet cmdTable0argMp
                                 `Set.union` Map.keysSet cmd1argMp
                                 `Set.union` Map.keysSet cmd2argMp
       , scoSpecChars        =   Set.fromList (specCharsOther ++ specCharsOpenClose ++ specCharsVBar ++ specCharsAt ++ specCharsAmpersand)
@@ -214,7 +229,7 @@ pTextItemsArg       ::  T2TPr TextItems
 pTextItemsArg       =   pTextItemsP pTextItemArg
 
 pTextItemsTbl       ::  T2TPr TextItems
-pTextItemsTbl       =   (:) <$> pTextItemTbl1 <*> pTextItemsP pTextItemTbl2
+pTextItemsTbl       =   (:) <$> pTextItemTbl1 <*> pTextItemsP pTextItemTbl2 `opt` []
 
 pTableItemsAftRowSep::  T2TPr TextItems
 pTableItemsAftRowSep=   pTextItemsP pTextItemSpace2
@@ -256,7 +271,7 @@ pTextItemBase3      =   pDelimBy "|" pTextItemSpecsAt (TextItem_Styled TextStyle
                     where pDelimBy delim extra sem
                             = pKey delim
                               *> (   TextItem_NonSpace <$> pKey delim
-                                 <|> sem <$> pList1 (pTextItemNonSpace <|> pTextItemSpace1 <|> extra) <* pKey delim
+                                 <|> sem <$> pList1 (pTextItemBase3Inside <|> extra) <* pKey delim
                                  )
 
 pTextItemSpecs      ::  (IsParser p Tok) => [String] -> p TextItem
@@ -288,8 +303,16 @@ pTextItemItem       =   TextItem_ItemizeItem <$ pCmd "item" <*> pTextItemsAll
 
 pTextItemOption     ::  T2TPr TextItem
 pTextItemOption     =   pTextItemBase1
+                    <|> pCmdPlain0Arg
                     <|> pTextItemSpace2
 
+pTextItemBase3Inside::  T2TPr TextItem
+pTextItemBase3Inside=   pTextItemNonSpace
+                    <|> pTextItemSpecsOther
+                    <|> pTextItemSpace1
+                    <|> pTextItemSpecsOC
+                    <|> pTextItemSpecsTbl2
+
 pTextItemArg        ::  T2TPr TextItem
 pTextItemArg        =   pTextItemOption
                     <|> pTextItemBase2
@@ -305,12 +328,12 @@ pTextItemAll        =   pTextItemArg
 
 pTextItemTbl1       ::  T2TPr TextItem
 pTextItemTbl1       =   pTextItemBase1
+                    <|> pCmdTable0Arg
                     <|> pTextItemBase2
                     <|> pTextItemBase3
                     <|> pTextItemSpecsOC
                     <|> pTextItemSpecsOther
                     <|> pTextItemKeyws
-                    <|> pTextItemSpecsVBar
 
 pTextItemTbl2       ::  T2TPr TextItem
 pTextItemTbl2       =   pTextItemTbl1
@@ -380,6 +403,12 @@ pGraphicsInlineOption
 pCmd0Arg            ::  T2TPr TextItem
 pCmd0Arg            =   pAnyFromMap pCmd cmd0argMp
 
+pCmdPlain0Arg       ::  T2TPr TextItem
+pCmdPlain0Arg       =   pAnyFromMap pCmd cmdPlain0argMp
+
+pCmdTable0Arg       ::  T2TPr TextItem
+pCmdTable0Arg       =   pAnyFromMap pCmd cmdTable0argMp
+
 pCmd1Arg            ::  T2TPr (TextItems -> TextItem)
 pCmd1Arg            =   pAnyFromMap pCmd cmd1argMp
 

src/text2text/Text/To/DocLaTeX.ag

@@ -104,7 +104,8 @@ SEM TextItem
   | Styled	  		loc			.	out			=   @style.out +++ dltxArg @text.out
   | VerbatimInline	loc			.	out			=   dltxCmd "verb" +++ @delim +++ @str +++ @delim
   | BreakLine		loc			.	out			=   dltxCmd "\\"
-  | HorRuler		loc			.	out			=   dltxCmd "hline"
+  | HorRuler TableHorRuler
+  					loc			.	out			=   dltxCmd "hline"
   | Header  		loc			.	out			=   @level.out +++ dltxArg @text.out
   | Group			loc			.	out			=	dltxBeginEnd @envtype.out @text.out
   | DocumentContent	loc			.	out			=	dltxBeginEnd "document" @text.out
@@ -118,11 +119,12 @@ SEM TextItem
   | MakeTitle       loc         .   out         =   dltxCmd "maketitle"
   | DocumentHeader  loc         .   out         =   dltxCmd "documentclass" +++ @mboptions.out +++ dltxArg @text.out
   | GraphicsInline  loc         .   out         =   let mkFig = if isJust @mboptions.mbCaption || isJust @mboptions.mbLabel
-                                                                then \x -> dltxOptsBeginEnd "figure" "[h]" x
+                                                                then \x -> dltxOptsBeginEnd "figure" "[ht]" x
                                                                 else id
+                                                        mkCen = dltxBeginEnd "center"
                                                         mkLbl = maybe id (\l x -> x +++ dltxCmd "label" +++ dltxArg l) @mboptions.mbLabel
                                                         mkCap = maybe id (\c x -> x +++ dltxCmd "caption" +++ dltxArg c) @mboptions.mbCaption
-                                                    in  mkFig $ mkCap $ mkLbl $ dltxCmd "includegraphics" +++ @mboptions.out +++ dltxArg @text.out
+                                                    in  mkFig $ mkCen $ mkCap $ mkLbl $ dltxCmd "includegraphics" +++ @mboptions.out +++ dltxArg @text.out
   | TOC             loc         .   out         =   dltxCmd "tableofcontents"
 
 SEM RefType

src/text2text/Text/To/TWiki.ag

@@ -55,27 +55,37 @@ isTWikiChar = isAlphaNum
 isTWikiWord :: String -> Bool
 isTWikiWord s
   = is 0 s
-  where is st (c:s') | isUpper c && (st == 0 || st == 2) = is (st+1) s'
+  where is st (c:_ ) | isLower c &&  st == 0             = False
+        is st (c:s') | isUpper c && (st == 0 || st == 2) = is (st+1) s'
         is st (c:s') | isLower c &&  st == 1             = is (st+1) s'
         is st (c:_ ) | not (isTWikiChar c)               = False
         is 3  _                                          = True
         is st (_:s')                                     = is  st    s'
         is _  _                                          = False
 }
 
+-------------------------------------------------------------------------
+-- Ensure text is for a TWiki anchor
+-------------------------------------------------------------------------
+
+{
+ensureTWikiAnchor :: Out a => a -> OutDoc
+ensureTWikiAnchor x = out $ filter isTWikiChar $ outToString $ out x
+}
+
 -------------------------------------------------------------------------
 -- Combinators
 -------------------------------------------------------------------------
 
 {
 dtwkLbl :: Out a => a -> OutDoc
-dtwkLbl a = "#T2TLabel" +++ (filter isTWikiChar $ outToString $ out a)
+dtwkLbl a = "#LabeL" +++ ensureTWikiAnchor a
 
 dtwkCmd :: Out c => c -> OutDoc
 dtwkCmd c = "%" +++ c +++ "%"
 
 dtwkHdr :: Int -> OutDoc
-dtwkHdr l = "---+" +++ replicate l '+' +++ " "
+dtwkHdr l = "\n---+" +++ replicate l '+' +++ " "
 
 dhtmTag :: Out a => a -> OutDoc
 dhtmTag a = "<" +++ a +++ ">"
@@ -119,7 +129,7 @@ type HeaderSeqNrMp = Map.Map Int Int
 }
 
 ATTR AllText AllTable [ | headerLevel: Int  headerSeqNrMp: HeaderSeqNrMp | ]
-ATTR HeaderLevel [ | headerLevel: Int | ]
+ATTR HeaderLevel [ | headerLevel: Int | allowHeaderCounting: Bool ]
 
 SEM AGItf
   | AGItf           loc         .   headerLevel =   -1
@@ -129,17 +139,25 @@ SEM AGItf
 SEM HeaderLevel
   | Level           lhs         .   headerLevel =   @level
 
+SEM HeaderLevel
+  | Level           lhs         .   allowHeaderCounting
+  												=   True
+  | Paragraph       lhs         .   allowHeaderCounting
+  												=   False
+
 SEM TextItem
   | Header          (loc.headerTxt,lhs.headerSeqNrMp)
-                                                =   let mkTxt h m = concat $ intersperse "." [ show $ fromJust $ Map.lookup l m | l <- [0 .. h] ]
-                                                        seqNr h = fromJust $ Map.lookup h @lhs.headerSeqNrMp
-                                                    in  case @lhs.headerLevel `compare` @level.headerLevel of
-                                                          GT -> ( mkTxt @level.headerLevel m, m )
-                                                                where m = Map.insert @level.headerLevel (seqNr @level.headerLevel + 1) @lhs.headerSeqNrMp
-                                                          EQ -> ( mkTxt @lhs.headerLevel m, m )
-                                                                where m = Map.insert @lhs.headerLevel (seqNr @lhs.headerLevel + 1) @lhs.headerSeqNrMp
-                                                          LT -> ( mkTxt @level.headerLevel m, m )
-                                                                where m = Map.insert @level.headerLevel 1 @lhs.headerSeqNrMp
+                                                =   if @level.allowHeaderCounting
+                                                    then let mkTxt h m = concat $ intersperse "." [ show $ fromJust $ Map.lookup l m | l <- [0 .. h] ]
+                                                             seqNr h = fromJust $ Map.lookup h @lhs.headerSeqNrMp
+                                                         in  case @lhs.headerLevel `compare` @level.headerLevel of
+                                                               GT -> ( mkTxt @level.headerLevel m, m )
+                                                                     where m = Map.insert @level.headerLevel (seqNr @level.headerLevel + 1) @lhs.headerSeqNrMp
+                                                               EQ -> ( mkTxt @lhs.headerLevel m, m )
+                                                                     where m = Map.insert @lhs.headerLevel (seqNr @lhs.headerLevel + 1) @lhs.headerSeqNrMp
+                                                               LT -> ( mkTxt @level.headerLevel m, m )
+                                                                     where m = Map.insert @level.headerLevel 1 @lhs.headerSeqNrMp
+                                                    else ( "", @lhs.headerSeqNrMp )
 
 -------------------------------------------------------------------------
 -- Itemize level
@@ -171,15 +189,25 @@ SEM AGItf
 -- How to make a reference
 -------------------------------------------------------------------------
 
-ATTR RefType [ | | mkRefOut: {OutDoc -> OutDoc -> OutDoc} ]
+ATTR RefType [ | | mkRefOut: {OutDoc -> OutDoc -> OutDoc} ] -- \reftext text -> ...
 
 SEM RefType
-  | Local           loc         .   mkRefOut    =   dtwkRef
+  | Local           loc         .   mkRefOut    =   \r t -> dtwkRef (dtwkLbl $ ensureTWikiAnchor r) t
   | Global          loc         .   mkRefOut    =   dtwkRef
   | EhcWeb          loc         .   mkRefOut    =   dtwkRef
   | EhcSrc          loc         .   mkRefOut    =   \r t -> t +++ " (" +++ dhtmOpenClose "code" r +++ ")"
   | Cite            loc         .   mkRefOut    =   \_ t -> t
 
+-------------------------------------------------------------------------
+-- How to make a section header
+-------------------------------------------------------------------------
+
+ATTR HeaderLevel [ | | mkHdrOut: {OutDoc -> OutDoc -> OutDoc} ] -- \numberingprefix text -> ...
+
+SEM HeaderLevel
+  | Level           loc         .   mkHdrOut    =   \n t -> dtwkHdr @level +++ n +++ t +++ "\n"
+  | Paragraph       loc         .   mkHdrOut    =   \_ t -> "\n*" +++ t +++ "*"
+
 -------------------------------------------------------------------------
 -- Selectively modifying wikiwords
 -------------------------------------------------------------------------
@@ -191,7 +219,7 @@ SEM AGItf
                                                 =   False
 
 SEM TextItem
-  | Label           loc         .   allowWikiWord
+  | Label Styled    loc         .   allowWikiWord
                                                 =   True
 
 -------------------------------------------------------------------------
@@ -215,10 +243,10 @@ SEM AGItf
 
 
 SEM TableField
-  | Fld             loc         .   allowLF     =   True
+  | Fld             loc         .   allowLF     =   False
 
 SEM TableRow
-  | Row             loc         .   allowLF     =   True
+  | Row             loc         .   allowLF     =   False
 
 SEM TextItem
   | Itemize         loc         .   allowLF     =   False
@@ -227,7 +255,7 @@ SEM TextItem
 
 SEM TextItem
   | Line LineFeed CommentLF
-                    loc         .   lf          =   mkLF @lhs.allowLF
+                    loc         .   lf          =   mkLF  @lhs.allowLF
   | ParBreak        loc         .   par         =   mkPar @lhs.allowLF
 
 -------------------------------------------------------------------------
@@ -249,12 +277,10 @@ SEM TextItem
   | VerbatimInline  loc         .   out         =   dhtmOpenClose "code" @str
   | BreakLine       loc         .   out         =   dtwkCmd "BR"
   | HorRuler        loc         .   out         =   out "\n------"
-  | Header          loc         .   out         =   @level.out
-                                                    +++ (if optGenHeaderNumbering @lhs.opts then @headerTxt +++ " " else emptyout)
-                                                    +++ @text.out +++ "\n"
+  | Header          loc         .   out         =   @level.mkHdrOut (if optGenHeaderNumbering @lhs.opts then @headerTxt +++ " " else emptyout) @text.out
   | Group           loc         .   out         =   dhtmOpenClose @envtype.out @text.out
   | DocumentContent loc         .   out         =   @text.out -- +++ "\n" +++ dtwkCmd "REVINFO{\"$date\"}"
-  | Table           loc         .   out         =   @extratext.out +++ @rows.out
+  | Table           loc         .   out         =   {- @extratext.out +++ -} outListSep "\n" "" "\n" @rows.outL
   | Itemize         loc         .   out         =   @text.out
   | ItemizeItem     loc         .   out         =   "\n" +++ @lhs.itemizePrefix +++ @text.out
   | Title           loc         .   out         =   emptyout
@@ -268,7 +294,7 @@ SEM TextItem
   | TOC             loc         .   out         =   dtwkCmd "TOC"
 
 SEM RefType
-  | Local           loc         .   out         =   dtwkLbl ""
+  | Local           loc         .   out         =   emptyout
   | Global          loc         .   out         =   emptyout
   | EhcWeb          loc         .   out         =   out "Ehc."
   | EhcSrc          loc         .   out         =   out "EHCHOME/"
@@ -287,6 +313,7 @@ SEM ItemizeStyle
   | Bullet          lhs         .   out         =   out "   * "
   | Number          lhs         .   out         =   out "   1 "
 
+{-
 SEM HeaderLevel
   | Level           lhs         .   out         =   dtwkHdr @level
   | Paragraph       lhs         .   out         =   out "\n"
@@ -296,21 +323,26 @@ SEM TableColFormat
   | JustifyCenter   loc         .   out         =   out "c"
   | JustifyRight    loc         .   out         =   out "r"
   | SepbyLine       loc         .   out         =   out "|"
+-}
 
 SEM TableRow
-  | Row             lhs         .   out         =   outListSep "|" "|" "|" @cols.outL +++ @extrabrktext.out
+  | Row             lhs         .   out         =   outListSep "|" "|" "|" @cols.outL -- +++ @extrabrktext.out
 
 SEM TableField
-  | Fld             lhs         .   out         =   @extraseptext.out +++ @fld.out
+  | Fld             lhs         .   out         =   {- @extraseptext.out +++ -} @fld.out
 
 -------------------------------------------------------------------------
 -- Replacement, as [OutDoc]
 -------------------------------------------------------------------------
 
 ATTR
-  TableFields
+  TableFields TableRows
     [ | | outL USE {++} {[]}: {[OutDoc]} ]
 
+SEM TableRows
+  | Cons            lhs         .   outL        =   @hd.out : @tl.outL
+  | Nil             lhs         .   outL        =   []
+
 SEM TableFields
   | Cons            lhs         .   outL        =   @hd.out : @tl.outL
   | Nil             lhs         .   outL        =   []

text/HowToDoc.cltex

@@ -41,7 +41,7 @@ The suffix \verb|xxx| currently can be \verb|pdf| or \verb|twiki|.
 %%[allocateVariant doclatex
 First a variant number must be allocated. All papers and documentation are constructed by \eref{Shuffle}{Shuffle} from a set of files holding \eref{Shuffle}{Shuffle}
 chunks.
-Of the various makefiles for producing text the \sref{text/files1-atze.mk}{makefile for text sources and variants} must include a definition for a new variant.
+Of the various makefiles for producing text the \sref{text/files-variants.mk}{makefile for text sources and variants} must include a definition for a new variant.
 A new variant is added by:
 
 \begin{enumerate}
@@ -58,7 +58,7 @@ TEXT_SHUFFLE_ORDER  += \
 The new documentation must be given a name which can be used for making and publishing the documentation:
 \begin{enumerate}
 \item Find an unused name, say \emph{my-doc}, and add it to the list in variable \verb|TEXT_DOC_VARIANTS|.
-\item Connect the name to the variant number by including a makefile target in the \sref{text/files2-atze.mk}{makefile for targets}.
+\item Connect the name to the variant number by including a makefile target in the \sref{text/files-targets.mk}{makefile for targets}.
 The target name must be of the form \verb|text-variant-<chosen-name>|:
 \begin{verbatim}
 text-variant-my-doc:
@@ -124,7 +124,7 @@ General topics use prefix \verb|Topic|, slides use \verb|Slides|. This conventio
 The following must be done:
 \begin{enumerate}
 \item Create (and add it to the repository, if necessary) \sref{text/ToolDocMy.cltex}{the documentation source file} and add its base name \verb|ToolDocMy| to the makefile variable
-\verb|TEXT_SUBS| in \sref{text/files1-atze.mk}{the makefile for text sources and variants}.
+\verb|TEXT_SUBS| in \sref{text/files-variants.mk}{the makefile for text sources and variants}.
 It will now be automatically used when \eref{Shuffle}{Shuffle} is invoked.
 \item Add content in \sref{text/ToolDocMy.cltex}{the documentation source file}, for example by:
 \begin{verbatim}