stx2any/0000755000175000017500000000000010471044066014126 5ustar pkalliokpkalliok00000000000000stx2any/man/0000755000175000017500000000000010471044066014701 5ustar pkalliokpkalliok00000000000000stx2any/man/make.lm40000644000175000017500000000653210471044066016242 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.man)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) Definitions for man. (Of course, we also use some raw troff and tbl.) Metadata man-ism: {{{ define(`w_section', `w_set_or_get(`@w_section', `$1')') define(`w_man_desc', `ifdef(`@w_man_has_desc',`.br',`.SH NAME')`'w_nl`'define(`@w_man_has_desc',t)'dnl `ifelse(`$2',,`w_title \- $1`'', `$1 \- $2`'')') }}} Paragraphs and headings. {{{ define(`w_softpara', `w_dump_footnotes(`.br`'w_nl`'',)`'dnl') define(`w_paragraph', `.PP`'w_nl') define(`w_headline', `ifelse(`$1',1,`.SH $2',`$1',2,`.SS $2', `$1',3,`.PP`'w_nl.B $2',`.PP`'w_nl.SB $2')') }}} Block system environments. Oh my god, do we do things by hand! It almost makes me happy of all the infrastructure we have for this. Paragraphs within list items have to be made special. We do list numbering by hand. List nesting is done via RS and RE, but it should probably have more complicated rules. {{{ w_define_env(`w_man_list', `pushdef(`w_paragraph', `.IP "" 4`'w_nl`'').RS 4`'w_nl`'', `.RE`'w_nl`'popdef(`w_paragraph')w_softopen') w_derive_env(`-', `w_man_list', 0,,,,) define(`w_listitem', `.IP \(bu 4`'w_nl\&') w_derive_env(`#', `w_man_list', 0, `w_newcounter(enumlist)',,,`w_delcounter(enumlist)') w_define_env(`#i', `w_stepcounter(enumlist).IP w_counter_arabic(enumlist). 4`'w_nl\&')') w_define_env(`q', `.RS 8`'w_nl`'', `.RE`'w_nl`'') define(`w_defnterm', `.TP`'w_nl`'\&$1`'') w_define_env(`t', `pushdef(`w_paragraph', `.TP`'w_nl\&w_nl`'')', `popdef(`w_paragraph')') w_define_env(`:', `.RS 3`'w_nl`'', `.RE`'w_nl`'w_softopen') }}} Other environments. {{{ w_define_env(`litblock', `w_beg_para.nf`'w_nl\fC', `\fP`'w_nl.fi') define(`w_footnotemark', `\&w_nl.SM [$1]w_nl\&') w_define_env(center, `.ce 10000`'w_nl`'', `.ce 0`'w_nl`'') w_define_env(comment, `pushdef(`w_softbr', `.\" ')pushdef(`w_softpara', `.\"')`'w_nl.\"', ``'popdef(`w_softbr')popdef(`w_softpara')w_nl\&') define(`w_caption', `.SM $1') }}} Emphasis. {{{ define(`w_literal', `\fC`'$1\fP`'') define(`w_emph', `\fI`'$1\fP`'') define(`w_strong', `\fB`'$1\fP`'') define(`w_quotation', `\(lq`'$1\(rq`'') }}} Other inlines. {{{ define(`w_linebr', `w_nl`'.br') define(`w_link', `$2`'w_footnote(`$1')') define(`w_img', `\&w_nl.PSPIC "w_file(`$1.'w_picture_suffix)"w_nl\&') define(`w_label', `$2') define(`w_refer', `$2') }}} Tables. tbl is very sensitive to white space. We try to protect from errors, but I really can't make sure that all combinations of markup and tables work. {{{ define(`w_make_tablespec', `ifelse(`$*',,,`ifelse(`$1',p,l,`$1') w_make_tablespec(shift($@))')') w_define_env(w_table, `pushdef(`w_eline',` \')\&w_nl`'.TS`'w_nl`'w_make_tablespec($@).w_nl`'', `\&w_nl`'.TE`'w_nl`'popdef(`w_eline')') w_define_env(w_row,, `undefine(`@w_in_row_flag')define(`w_eline',`define(`w_eline',` \')')') w_define_env(w_cell, `ifdef(`@w_in_row_flag',` ')define(`@w_in_row_flag',t)'dnl `ifelse(`$2',p,`T{w_nl\&')', `ifelse(`$2',p,`\&w_nl`'T}')') define(`w_table_rule', `_') }}} Special and quoted characters. {{{ define(`w_bldot', `\&.') define(`w_bs', `\\') define(`w_blap', `\&w_apo') define(`w_emdash', `\`('em') define(`w_endash', `\-') define(`w_ellipsis', `.\|.\|.') define(`w_copyrightsign', `\`('co') define(`w_trademarksign', `\`('tm') define(`w_rarrow', `\`('->') define(`w_larrow', `\`('<-') }}} stx2any/man/settings.lsh0000644000175000017500000000030210424125243017237 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ test -z "$NUMBERING" && NUMBERING=off test -z "$PIC_SUFFIX" && PIC_SUFFIX=eps }}} stx2any/man/templ.lm40000644000175000017500000000060310424125216016432 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ .TH "defn(`@w_title')" "defn(`@w_section')" "defn(`@w_date')" "defn(`@w_author')" ifdef(`@w_iso_language',`.hla defn(`@w_iso_language')',`dnl') w_dumpdiv(frontmatter)dnl w_dumpdiv(ingr)dnl ifelse(w_make_toc,true,`w_dumpdiv(toc)')dnl w_dumpdiv(body) w_dumpdiv(backmatter) }}} stx2any/TODO0000644000175000017500000000134410423671243014620 0ustar pkalliokpkalliok00000000000000 - Features: * end-section notes * e-mail style block quotes * make footnotes only from indirect link abbrevs * a citing / bibliography system, support for cites in generic links? - but it can be quite nicely handled with link abbrevs already... * abbreviations for environments * python and/or scheme implementation - Bugs: * How to deal with the dissimilarity of LaTeX tables and other tables? * Clean up gather_stx_titles? * Clean up caption system... - Tests that remain to be written: * tests for quote interactions (phooie) * hook tests: temporary redefinition of macros * command line options? * cross links * html2stx tests - Documentation: * adding new output formats * extensions (with w_use) stx2any/html/0000755000175000017500000000000010446213102015061 5ustar pkalliokpkalliok00000000000000stx2any/html/make.lm40000644000175000017500000000750410424125200016417 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.html)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) Definitions for HTML. HTML provides its own hack diversion, ''metas''. {{{ w_define_div(metas) }}} Paragraphs and headings. {{{ define(`w_softpara', `w_dump_footnotes(
,)') define(`w_paragraph', `

') define(`w_headline', `$2') }}} Block system environments. {{{ w_define_env(-,

) w_define_env(#,
    ,
) define(`w_listitem', `
  • ') w_define_env(q,
    ,
    ) w_define_env(:, `pushdef(`w_pending_block_hook',)
    ', `popdef(`w_pending_block_hook')
    ') define(`w_defnterm', `
    $1
    ') w_define_env(t, `define(`w_pending_block_hook',
    )', `ifelse(defn(`w_pending_block_hook'),,
    , `define(`w_pending_block_hook',)')') }}} Other environments. {{{ w_define_env(litblock, `undefine(`@w_para_flag')
    ', `
    ') define(`w_footnotemark', `[$1]') w_define_env(center, `
    ', `
    ') w_define_env(comment, `') w_derive_env(`w_float_m', `w_float_h', 0, `
    ',,,`
    ') define(`w_caption', `$1') }}} Emphasis. {{{ define(`w_literal', `$1') define(`w_emph', `$1') define(`w_techemph', `$1') define(`w_strong', `$1') define(`w_quotation', `$1') }}} Other inlines. {{{ define(`w_linebr',
    ) define(`w_sectbreak', `
    ') define(`w_link', `$2') define(`w_img', `$2') define(`w_label', `$2') define(`w_refer', `$2') define(`w_url', `w_link(`$1', `$1')') }}} Slides. {{{ w_define_env(slide, `w_ensure_slides
    ', `
    ') define(`w_ensure_slides', `ifdef(`@w_slidesetup_done',, `define(`@w_slidesetup_done',t)w_slide_setup')') ifdef(`w_s5url',,`define(`w_s5url', `ui/default/')') define(`w_slide_setup', `define(`w_s5url', w_file(defn(`w_s5url')))'dnl `w_begdiv(metas) w_enddiv(metas)w_begdiv(frontmatter)
    w_enddiv(frontmatter)w_begdiv(ingr)
    w_enddiv(ingr)w_begdiv(backmatter)
    w_enddiv(backmatter)undefine(`w_make_title')') }}} Tables. {{{ w_define_env(w_table, `pushdef(`w_caption', `$1')', `popdef(`w_caption')
    ') w_define_env(w_row, `', `') w_define_env(w_cell, `', `') define(`w_table_rule', `
    ') }}} Special and quoted charactes. {{{ define(`w_lt', `<') define(`w_gt', `>') define(`w_amp', `&') define(`w_emdash', `—') define(`w_endash', `–') define(`w_ellipsis', `…') define(`w_copyrightsign', `©') define(`w_trademarksign', `™') define(`w_larrow', `←') define(`w_rarrow', `→') }}} stx2any/html/settings.lsh0000644000175000017500000000030210424125241017426 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ test -z "$NUMBERING" && NUMBERING=off test -z "$PIC_SUFFIX" && PIC_SUFFIX=png }}} stx2any/html/templ.lm40000644000175000017500000000156110424125203016623 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ defn(`@w_title') ifelse(defn(`@w_date'),,`dnl',` ') w_dumpdiv(metas)dnl w_dumpdiv(frontmatter)dnl ifelse(w_make_title,true, `ifelse(defn(`@w_title'),,`dnl',`

    defn(`@w_title')

    ')') w_dumpdiv(ingr)dnl ifelse(w_make_toc,true,`w_dumpdiv(toc)')dnl w_dumpdiv(body)dnl w_dumpdiv(backmatter)dnl }}} stx2any/Makefile0000644000175000017500000000604310423671243015571 0ustar pkalliokpkalliok00000000000000 BUILD_USAGE_WITH=w3m INSTALL=install -c STX2ANY=./scripts/stx2any PREFIX=/usr BASE=$(DESTDIR)$(PREFIX) EXEDIR=$(BASE)/bin LIBDIR=$(BASE)/share/stx2any MANDIR=$(BASE)/share/man/man1 MSGDIR=$(LIBDIR)/messages EMACSDIR=$(BASE)/share/emacs/site-lisp SCRIPTS=stx2any strip_stx gather_stx_titles html2stx extract_usage_from_stx MANPAGES:=$(SCRIPTS:=.1) MESSAGES:=$(SCRIPTS:=.usage) version.msg INST_SCRIPTS=$(SCRIPTS:=.inst) DOCDIR=$(BASE)/share/doc/stx2any DOCBASE:=stx2any Stx-doc Stx-ref strip_stx gather_stx_titles html2stx \ accreditions extract_usage_from_stx DOCBASE:=$(DOCBASE:%=examples/%) DOCS:=$(DOCBASE:=.html) $(MANPAGES) examples/README.html FORMATS=html man latex docbook-xml COMMON=common.m4 markup.m4 begin.m4 end.m4 cleanup.m4 secure.m4 templ.m4 \ emphasis.sed inline.sed block.sed quote.sed quote_us.sed wrapcalls.sed \ gatherlinkmap.sed linking.sed quote_quotes.sed header.sed STXDEFS:=$(FORMATS:=/make.m4) $(FORMATS:=/templ.m4) $(FORMATS:=/settings.sh) \ $(COMMON:%=common/%) .SUFFIXES: all: chmod doc $(MESSAGES) $(INST_SCRIPTS) $(STXDEFS) chmod: chmod +x scripts/* regression/run-tests html2stx.inst: scripts/html2stx cp $< $@ %.inst: scripts/% sed -e "s#^BASE=.*#BASE="$(LIBDIR)"#" $< >$@ %.1: examples/%.txt $(STXDEFS) sed -e "s#PREFIX#$(PREFIX)#" $< | $(STX2ANY) -T man >$@ %.usage: examples/%.txt $(STXDEFS) ifeq ($(BUILD_USAGE_WITH),w3m) ./scripts/extract_usage_from_stx $< | $(STX2ANY) -T text >$@ else ./scripts/extract_usage_from_stx $< >$@ endif version.msg: debian/changelog sed -e 's#^\([^(]*\)(\([^)]*\)).*#\1\2#' -e '1q' $< >$@ %.m4: %.lm4 ./scripts/strip_stx $< >$@ %.sh: %.lsh ./scripts/strip_stx $< >$@ %.sed: %.lsed ./scripts/strip_stx $< >$@ test: chmod $(STXDEFS) ./regression/run-tests doc: chmod $(DOCS) install: all $(INSTALL) -m 755 -d $(EXEDIR) $(LIBDIR) $(MSGDIR) $(MANDIR) $(DOCDIR) $(EMACSDIR) for i in $(INST_SCRIPTS); do \ $(INSTALL) -m 755 $$i $(EXEDIR)/`basename $$i .inst`; \ done $(INSTALL) -m 644 $(MANPAGES) $(MANDIR) $(INSTALL) -m 644 $(DOCS) $(DOCBASE:=.txt) $(MISC) $(DOCDIR) $(INSTALL) -m 644 stx-mode.el $(EMACSDIR) for i in $(FORMATS); do \ $(INSTALL) -m 755 -d $(LIBDIR)/$$i; \ $(INSTALL) -m 644 $$i/*.m4 $$i/*.sh $(LIBDIR)/$$i; \ done $(INSTALL) -m 755 -d $(LIBDIR)/common $(INSTALL) -m 644 common/*.m4 common/*.sed $(LIBDIR)/common $(INSTALL) -m 644 $(MESSAGES) $(MSGDIR) titles.m4: $(DOCBASE:=.txt) common/header.sed ./scripts/gather_stx_titles -p examples -f txt -t html $^ > $@ examples/README.html: README titles.m4 $(STXDEFS) $(STX2ANY) --link-abbrevs titles.m4 $< > $@ examples/Stx-doc.html: examples/Stx-doc.txt titles.m4 $(STXDEFS) $(STX2ANY) --link-abbrevs titles.m4 $< > $@ examples/Stx-ref.html: examples/Stx-ref.txt titles.m4 $(STXDEFS) $(STX2ANY) --numbering on titles.m4 $< > $@ %.html: %.txt titles.m4 $(STXDEFS) $(STX2ANY) titles.m4 $< > $@ clean: gc clean-leavedocs rm -f $(DOCS) gc: rm -f *.dvi *.toc *.log *.aux clean-leavedocs: rm -f $(STXDEFS) $(INST_SCRIPTS) $(MESSAGES) titles.m4 .PHONY: clean gc clean-leavedocs all doc install test chmod stx2any/regression/0000755000175000017500000000000010471044066016306 5ustar pkalliokpkalliok00000000000000stx2any/regression/metadata.html0000644000175000017500000000074010423671243020755 0ustar pkalliokpkalliok00000000000000 The Title

    The Title

    The Title — introduction

    This is the day/month/year version, written by Author Name. stx2any/regression/metadata.test0000644000175000017500000000031710423671243020770 0ustar pkalliokpkalliok00000000000000title: The Title doc_id: metadata-test author: Author Name date: day/month/year section: 8 language: english char_coding: ascii ! w_title -- introduction This is the "w_date" version, written by w_author. stx2any/regression/weird.titles0000644000175000017500000000164210423671243020651 0ustar pkalliokpkalliok00000000000000define(`@w_file_exists_ession/abbrev.test', t)dnl define(`@w_file_exists_ession/crossref.test', t)dnl define(`@w_file_exists_ession/defn-nest.test', t)dnl define(`@w_file_exists_ession/link-abbrev-bug.test', t)dnl define(`@w_file_exists_ession/link-abbrev.test', t)dnl define(`@w_file_exists_ession/link-abbrev-toc.test', t)dnl define(`@w_file_exists_ession/list.test', t)dnl define(`@w_file_exists_ession/markup.test', t)dnl define(`@w_file_exists_ession/metadata.test', t)dnl define(`@w_file_exists_ession/slid', t)dnl define(`@w_file_exists_ession/tabl', t)dnl define(`@w_file_exists_ession/underscor', t)dnl define(`@w_filename_of_crossref-test', `ession/crossref.test')dnl define(`@w_title_of_'`ession/metadata.test', `The Title')dnl define(`@w_filename_of_metadata-test', `ession/metadata.test')dnl define(`@w_title_of_'`ession/slid', `slide test')dnl define(`@w_title_of_'`ession/underscor', `underscore quoting tests')dnl stx2any/regression/metadata.latex0000644000175000017500000000060410423671243021125 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper]{article} \usepackage[english]{babel} \usepackage[T1]{fontenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{The Title} \author{Author Name} \date{day/month/year} \begin{document} \maketitle \tableofcontents \section{The Title --- introduction} This is the ``day/month/year'' version, written by Author Name. \end{document} stx2any/regression/link-abbrev.man0000644000175000017500000000416710423671243021207 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" .SH Testing link abbreviations .PP First paragraph. It does not have anything weird. .PP Second paragraph. It doesn't have anything weird, either. There's just a line that begins with something that looks quite a lot like a \& .SM [1] \& block. Do we manage it? .br \& .SM [1] \& linkdata .br .PP Okay, now for the real\& .SM [2] \& thing. There should be all kinds of\& .SM [3] \& links here. See \(lqTesting link abbreviations\(rq to get a hold of what they all mean\& .SM [4] \&. \& .SM [5] \&. .br \& .SM [2] \& mailto:some.email@address.fi .br \& .SM [3] \& ftp://ftp.spoogle.com/ .br \& .SM [4] \& http://www.meaning.org/ .br \& .SM [5] \& This is a longer footnote, possibly spanning multiple lines. .br .PP There are longer links: \fCftp://ftp.rfc-editor.org/in-notes/rfc1355.txt\fP and friends. The problem with URIs is that you\& .SM [6] \& have hard time knowing where they stop. Take for example \fChttp://www.plt-scheme.org/\fP: why is the slash included but the colon not\& .SM [7] \&? (Another example is \fChttp://c2.com/cgi/quickChanges\fP, or \fChttp://sange.fi/~atehwa/index.html\fP.\|.\|.) .br \& .SM [6] \& the reader .br \& .SM [7] \& Don't tell me that properly quoted URI's won't have colons in such positions. People never properly quote URI's, as required by RFC2396. .br .PP Here is also an \& .PSPIC "pictures/zebra.eps" \&. Please jump back. I want you to consider an unadored relative link\& .SM [8] \& and another\& .SM [9] \&. .br \& .SM [8] \& ./foo.html .br \& .SM [9] \& ../index.html .br .PP Does the old-style footnote\& .SM [10] \& work anymore in the presence of link abbreviations\& .SM [11] \&?\& .SM [12] \& .br \& .SM [10] \& such as this one here .br \& .SM [11] \& as tested by this file .br \& .SM [12] \& And does it work if broken into multiple lines? .br .SS Explicit label (is not guaranteed to work properly) .PP How do multiple labels in the same line work? What about Second-label conflicts? .PP \(em \(em \(em .PP This is an interesting way to produce a bibliography: .PP RFC2396: Uniform Resource Identifies (URI): Generic Syntax (\fCftp://ftp.rfc-editor.org/in-notes/rfc2396.txt\fP) stx2any/regression/metadata.param0000644000175000017500000000002710423671243021107 0ustar pkalliokpkalliok00000000000000--latex-params a4paper stx2any/regression/list.man0000644000175000017500000000274010423671243017761 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" .RS 4 .IP \(bu 4 \&a .IP \(bu 4 \&b .RE .RS 4 .IP \(bu 4 \&c .IP \(bu 4 \&d .RS 4 .IP \(bu 4 \&e .RS 4 .IP 1. 4 \&f .IP 2. 4 \&g # foo .RE .IP \(bu 4 \&inner .RS 4 .IP 1. 4 \&zoo .IP 2. 4 \&boo .RE .RS 4 .IP 1. 4 \&new list .IP 2. 4 \&item2 .RE .RS 8 .IP "" 4 quote? .RE quote? .RE .IP "" 4 quote? .RE .PP \(em interlude \(em .RS 4 .IP \(bu 4 \&one .IP \(bu 4 \&two .IP \(bu 4 \&three in a row for a cow .IP \(bu 4 \&four .RS 3 .TP \&this is so as definitions go too low .RE .IP "" 4 final blow .IP \(bu 4 \&five .IP "" 4 it's alive .RS 8 consider quote .RE back we go .RE .RS 4 .IP \(bu 4 \&list intercept .RS 3 .TP \&this is the term show some respect .RE .IP "" 4 it is so firm .IP \(bu 4 \&the problem's not here anymore .RE .RS 3 .TP \&term one .RS 4 .IP \(bu 4 \&lists are fun .RE .TP \& the fun's begun .TP \&term two definitions, too! another for you. .TP \& They can have paragraphs .TP \&term three a .TP \&term three b a tree is a tree .br be or not to be? .RS 4 .IP \(bu 4 \&what's happening to me? .RE .RS 4 .IP \(bu 4 \&be or not to be? .RE .RS 4 .IP \(bu 4 \&what can you say? .RE .RE .RS 4 .IP \(bu 4 \&what's for the delay? .RE .RS 4 .IP \(bu 4 \&let's play .RE .PP \(em interlude 2 \(em .RS 4 .IP \(bu 4 \&foo foo2 .RS 4 .IP \(bu 4 \&bar bar2 .RE .RE .RS 4 .IP \(bu 4 \&baz baz2 .RS 4 .IP \(bu 4 \&quux quux2 .IP \(bu 4 \&fooox \& .SM [1] \& fooox2 \& .SM [2] \& fooox3 .RS 4 .IP \(bu 4 \&koe .br \& .SM [1] \& footnote? .br \& .SM [2] \& footnote? .br .RE .RE .RE stx2any/regression/defn-nest.man0000644000175000017500000000142410423671243020667 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" .RS 3 .TP \&foo .RS 4 .IP \(bu 4 \&bar .IP \(bu 4 \&baz .IP \(bu 4 \&quux .RE .TP \& hyvin toimii .TP \&foo2 .RE .RS 4 .IP \(bu 4 \&bar2 .IP \(bu 4 \&baz2 .IP \(bu 4 \&quux2 .RE .RS 3 .TP \&[foo3] hakasuluissa .RE .RS 4 .IP \(bu 4 \&meep .RE .PP huonosti toimii .RS 3 .TP \&foo3 .RS 4 .IP 1. 4 \&flooz .IP 2. 4 \&sooz .RE .RE .RS 4 .IP 1. 4 \&mooz .IP 2. 4 \&booz .RS 4 .IP 1. 4 \&dooz .IP 2. 4 \&klooz .RE .RE .RS 3 .TP \&foo4 Kiitos .RE .RS 3 .TP \&foo5 .RE .RS 4 .IP \(bu 4 \&ekkooo .IP \(bu 4 \&tokkoo .RE .PP Ja vielä: .RS 3 .TP \&foo6 .RE .RS 4 .IP \(bu 4 \&ekkkooo .IP \(bu 4 \&tokkoooo .RE .RS 3 .TP \&defnlist .TP \& foo .RS 3 .TP \&nested defn bar .TP \&nested defn 2 baz .RE .TP \& continuation .TP \&defnlist2 .RS 3 .TP \&immediate nested defn stuff .RE .RE stx2any/regression/link-abbrev-bug.docbook-xml0000644000175000017500000000045110423671243023415 0ustar pkalliokpkalliok00000000000000

    A BB C
    stx2any/regression/abbrev.man0000644000175000017500000001027210423671243020246 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" 1 headline 1 .br 1.1 headline 2 .br 1.1.1 headline 3 .br 1.1.1.1 headline 4 .br 1.2 miscellaneous inline .br 1.3 footnotes .br 1.3.1 \& .SM [8] \& in heading .br 1.4 section breaking .br 1.4.1 headline .br 1.4.2 another headline .br 1.4.3 headline followed by .br 1.4.4 two adjacent .br 1.4.5 headlines .br 1.5 preformatted .br 1.6 special characters .br .SH 1 headline 1 .SS 1.1 headline 2 .PP .B 1.1.1 headline 3 .PP .SB 1.1.1.1 headline 4 .SS 1.2 miscellaneous inline .PP end of line, \(lqquoted stuff\(rq end of line, \fIemphasised stuff\fP end of line, \fBstrongly emphasised stuff\fP end of line, \fCliteral-formatted stuff\fP. .PP \(lqquoted stuff\(rq, at the beginning of line\& .SM [1] \& /emphasised / not, \fIanother try\fP; \fInested \fBemphasis\fP for kiddies\fP-- \fCliteral-formatted stuff .br spanning multiple lines\fP, \fIemphasis\fP improperly \fInested \fBemphasis markers\fP spanning multiple lines\fP for fun .br \& .SM [1] \& this is a footnote .br .PP very \(lqlong quoted string with \fB/inner/ emphasis\fP and other way \fI*around* for them\fP if you please and goodies\(rq to try (\fBthank you\fP) .PP Emphasis \(lq\fIwithin\fP\(rq quotes Quotes \fI\(lqwithin\(rq\fP emphasis Strongem \(lq\fBwithin\fP\(rq quotes Quotes \fB\(lqwithin\(rq\fP strongem Literal \(lq\fCwithin\fP\(rq quotes Quotes \fC\(lqwithin\(rq\fP literal Literal \fI''within''\fP emphasis Emphasis \fC_within_\fP literal Literal \fB''within''\fP strongem Strongem \fC*within*\fP literal Quoted "quotes" for you Quoted _emphasis_ for you Quoted *strongem* for you Quoted ''litfmt'' for you .PP unmatched end-of-emphasis/ marker "Different * emphasis / characters "" out '' of ''' context '''' j .PP proper /path/to/file and its literal cousin, \fC/path/to/file\fP .PP Some */random mixed** \(lq\fIemphasis\fP\(rq mark*ers \& .SM [2] \& .br \& .SM [2] \& and a footnote that \fIhas multiple lines\fP .br .PP *strongemph*broken by* char /emphasis/broken by/ char \fCliteral'not broken by\fP char ''literal''broken by'' char .PP \fCliteral'with quotes\fP not broken anymore .PP \fCliteral'spanning multiple lines\fP not broken by char .PP *strongemph * broken by* space-sep char /emphasis / broken by/ space-sep char One char \fIc\fP emph One char \fBc\fP strongemph .PP (underscores) .PP \fIemphasis\fP type 1 an underscore _ by \fIitself\fP; between_words double _nested \fIemphasis\fP for_ convenience This _should_not_ work .PP (line breaking) .PP // begin in the // middle end-line .br end-paragraph .br .SS 1.3 footnotes .PP footnotes\& .SM [3] \& should be properly // numbered.\& .SM [4] \& Does it not seem to be\& .SM [5] \& so? .br \& .SM [3] \& footnote 1 for your pleasure .br \& .SM [4] \& footnote 2 .br \& .SM [5] \& a word with very many meanings .br .PP This\& .SM [6] \& is bad practice .PP .B 1.3.1 \& .SM [7] \& in heading .br \& .SM [6] \& footnote 4 .br \& .SM [7] \& footnote .br \& .SM [8] \& footnote .br .PP text .SS 1.4 section breaking .PP Paragraph followed by adjacent .PP .B 1.4.1 headline Paragraph in between .PP .B 1.4.2 another headline .PP Some text .PP .B 1.4.3 headline followed by .PP normal text .PP .B 1.4.4 two adjacent .PP .B 1.4.5 headlines .PP Paragraph followed by .PP \(em \(em \(em .PP section marker .PP \(em \(em \(em .PP both section markers here are adjacent .PP \(em \(em \(em .PP Some text .PP \(em \(em \(em \(em \(em .PP Once more .PP \(em \(em \(em \(em \(em .PP \(em \(em \(em \(em \(em .SS 1.5 preformatted .PP {{{Block}}} .PP Another block: .nf \fC content content content \fP .fi .PP And then: .PP .nf \fC content content content [empty line above] \fP .fi followed by an explanation. .RS 4 .IP \(bu 4 \&this one is within a list, I reckon: .nf \fC /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" \fP .fi .RS 4 .IP \(bu 4 \&embedded list and literal block: .IP "" 4 .nf \fC foo /bar/ \fP .fi .RE .RE .SS 1.6 special characters .PP Hello World!\(tm is a common program \(-> stupid. stupid \(<- me, also. .PP This is a range in January\-February of 2004. There are some special considerations\(emsuch as the em dash here. How many test do you need for changing a light bulb?\(emI guess 6\-8. .RS 8 .PP \(emblockquote ends this thing\(em .RE stx2any/regression/crossref.latex0000644000175000017500000000145710423671243021202 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle This goes into the ingress (\pageref{This.goes.into.the.ingress})\\ \tableofcontents This test is \copyright{} 1851 E. A. Poe. --- I think. Making \label{smooth}smooth transitions is \label{hard}hard work. It's not worth hardening the \label{hard1}hard; you should look into means of making things go more smoothly. \label{This.goes.into.the.ingress}This goes into the ingress Thank you for listening\ldots{} the \label{percussions}percussions. smooth (\pageref{smooth})\\ hard (\pageref{hard})\\ hard (\pageref{hard1})\\ percussions (\pageref{percussions})\\ \end{document} stx2any/regression/crossref.param0000644000175000017500000000002610423671243021154 0ustar pkalliokpkalliok00000000000000--symmetric-crossrefs stx2any/regression/link-abbrev-bug.man0000644000175000017500000000004110423671243021745 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" A .PP BB .PP C stx2any/regression/link-abbrev-bug.sed0000644000175000017500000000001110423671243021742 0ustar pkalliokpkalliok00000000000000s/B/&&/g stx2any/regression/crossref.html0000644000175000017500000000214510423671243021024 0ustar pkalliokpkalliok00000000000000 This goes into the ingress

    This test is © 1851 E. A. Poe. — I think. Making smooth transitions is hard work. It's not worth hardening the hard; you should look into means of making things go more smoothly.

    This goes into the ingress

    Thank you for listening… the percussions.

    smooth
    hard
    hard
    percussions
    stx2any/regression/crossref.test0000644000175000017500000000070410423671243021036 0ustar pkalliokpkalliok00000000000000w_begdiv(defs) w_doc_id(crossref-test) w_define_div(index) w_indexword(index, hard) w_indexword(index, smooth) w_indexword(index, percussions) w_enddiv(defs)dnl This test is (c) 1851 E. A. Poe. -- I think. Making smooth transitions is hard work. It's not worth hardening the hard; you should look into means of making things go more smoothly. w_index(ingr, This goes into the ingress) Thank you for listening... the percussions. w_dumpdiv(index) stx2any/regression/slide.latex0000644000175000017500000000114010423671243020441 0ustar pkalliokpkalliok00000000000000\documentclass[a4,notitlepage]{seminar} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{slide test} \author{somebody} \date{??.??.????} \newpagestyle{slidepage} {\hfill{}slide test\hfill{}}{\hfill{}somebody ??.??.????\hfill{}} \begin{document} \slidepagestyle{slidepage} \begin{slide} This is a slide. \begin{itemize} \item markup should work ordinarily. \item nothing special here, either. \end{itemize} \end{slide} \begin{slide} \section*{Important points} This is the second slide. \end{slide}\end{document} stx2any/regression/link-abbrev.latex0000644000175000017500000000500010423671243021534 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \usepackage{url} \usepackage{graphicx} \begin{document} \maketitle \section*{\label{Testing.link.abbreviations}Testing link abbreviations} First paragraph. It does not have anything weird. \label{Second.paragraph}Second paragraph. It doesn't have anything weird, either. There's just a line that begins with something that looks quite a lot like a \footnote{linkdata} block. Do we manage it? Okay, now for the real\footnote{\url{mailto:some.email@address.fi}} thing. There should be all kinds of\footnote{\url{ftp://ftp.spoogle.com/}} links here. See ``Testing link abbreviations (\pageref{Testing.link.abbreviations})'' to get a hold of what they all mean\footnote{\url{http://www.meaning.org/}}. \footnote{This is a longer footnote, possibly spanning multiple lines.}. There are longer links: \url{ftp://ftp.rfc-editor.org/in-notes/rfc1355.txt} and friends. The problem with URIs (\pageref{RFC2396}) is that you\footnote{the reader} have hard time knowing where they stop. Take for example \url{http://www.plt-scheme.org/}: why is the slash included but the colon not\footnote{Don't tell me that properly quoted URI's won't have colons in such positions. People never properly quote URI's, as required by RFC2396 (\pageref{RFC2396}).}? (Another example is \url{http://c2.com/cgi/quickChanges}, or \url{http://sange.fi/~atehwa/index.html}\ldots{}) Here is also an \includegraphics{pictures/zebra.eps}. Please jump back (\pageref{Second.paragraph}). I want you to consider an unadored relative link\footnote{\url{./foo.html}} and another\footnote{\url{../index.html}}. Does the old-style footnote\footnote{such as this one here} work anymore in the presence of link abbreviations\footnote{as tested by this file}?\footnote{And does it work if broken into multiple lines?} \subsection*{\label{w.autolabel.Explicit.label...is.not.guaranteed.to.work.properly.}\label{Explicit.label}Explicit label (is not guaranteed to work properly)} How do \label{multiple.labels}multiple labels in the same line \label{work}work? What about \label{Second.label.conflicts}Second-label conflicts? \begin{center}\rule{0.5\textwidth}{0.04em}\end{center} This is an interesting way to produce a bibliography: \label{RFC2396}RFC2396: Uniform Resource Identifies (URI): Generic Syntax (\url{ftp://ftp.rfc-editor.org/in-notes/rfc2396.txt}) \end{document} stx2any/regression/slide.param0000644000175000017500000000003310423671243020424 0ustar pkalliokpkalliok00000000000000--numbering off -Dw_s5url= stx2any/regression/underscore.docbook-xml0000644000175000017500000000214010423671243022614 0ustar pkalliokpkalliok00000000000000

    underscore quoting tests This should receive emphasis This might not receive emphasis This _ probably should receive emphasis Underscores _f nested b_ and between_words Continuing multiple lines should work Even now it should probably work indeed foobar empha not_empha can't foobar empha not_empha can't This is line: 20 in file: stdin
    In blockquote, how does an em dash — even a little one — work at the beginning of a line? (This has nothing to do with underscores.)
    stx2any/regression/link-abbrev.param0000644000175000017500000000003710423671243021524 0ustar pkalliokpkalliok00000000000000--numbering off --link-abbrevs stx2any/regression/crossref.docbook-xml0000644000175000017500000000264110423671243022277 0ustar pkalliokpkalliok00000000000000
    This goes into the ingress This test is © 1851 E. A. Poe. — I think. Making smooth transitions is hard work. It's not worth hardening the hard; you should look into means of making things go more smoothly. This goes into the ingress Thank you for listening… the percussions. smooth hard hard percussions
    stx2any/regression/underscore.man0000644000175000017500000000113010423671243021147 0ustar pkalliokpkalliok00000000000000.TH "underscore quoting tests" "" "" "" .PP This should receive \fIemphasis\fP This \fImight\fP not receive \fIemphasis\fP This _ probably should receive \fIemphasis\fP Underscores _f \fInested\fP b_ and between_words .PP Continuing \fImultiple lines\fP should work .PP \fBEven now\fP it \fIshould probably\fP work indeed .PP foobar \fIempha\fP not_empha \fIcan't\fP foobar \fIempha\fP not_empha \fIcan't\fP .PP This is line: 20 in file: stdin .RS 8 .PP In blockquote, how does an em dash \(em even a little one \(em work at the beginning of a line? (This has nothing to do with underscores.) .RE stx2any/regression/metadata.docbook-xml0000644000175000017500000000067110423671243022232 0ustar pkalliokpkalliok00000000000000
    The Title Author Name The Title — introduction This is the day/month/year version, written by Author Name.
    stx2any/regression/abbrev.latex0000644000175000017500000001040610423671243020607 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \usepackage{alltt} \begin{document} \maketitle \tableofcontents \section{headline 1} \subsection{headline 2} \subsubsection{headline 3} \paragraph{headline 4} \subsection{miscellaneous inline} end of line, ``quoted stuff'' end of line, \emph{emphasised stuff} end of line, \strongemph{strongly emphasised stuff} end of line, \litfmt{literal-formatted stuff}. ``quoted stuff'', at the beginning of line\footnote{this is a footnote} /emphasised / not, \emph{another try}; \emph{nested \strongemph{emphasis} for kiddies}-- \litfmt{literal-formatted stuff \\ spanning multiple lines}, \emph{emphasis} improperly \emph{nested \strongemph{emphasis markers} spanning multiple lines} for fun very ``long quoted string with \strongemph{/inner/ emphasis} and other way \emph{*around* for them} if you please and goodies'' to try (\strongemph{thank you}) Emphasis ``\emph{within}'' quotes Quotes \emph{``within''} emphasis Strongem ``\strongemph{within}'' quotes Quotes \strongemph{``within''} strongem Literal ``\litfmt{within}'' quotes Quotes \litfmt{``within''} literal Literal \emph{''within''} emphasis Emphasis \litfmt{_within_} literal Literal \strongemph{''within''} strongem Strongem \litfmt{*within*} literal Quoted "quotes" for you Quoted _emphasis_ for you Quoted *strongem* for you Quoted ''litfmt'' for you unmatched end-of-emphasis/ marker "Different * emphasis / characters "" out '' of ''' context '''' j proper /path/to/file and its literal cousin, \litfmt{/path/to/file} Some */random mixed** ``\emph{emphasis}'' mark*ers \footnote{and a footnote that \emph{has multiple lines}} *strongemph*broken by* char /emphasis/broken by/ char \litfmt{literal'not broken by} char ''literal''broken by'' char \litfmt{literal'with quotes} not broken anymore \litfmt{literal'spanning multiple lines} not broken by char *strongemph * broken by* space-sep char /emphasis / broken by/ space-sep char One char \emph{c} emph One char \strongemph{c} strongemph (underscores) \emph{emphasis} type 1 an underscore _ by \emph{itself}; between_words double _nested \emph{emphasis} for_ convenience This _should_not_ work (line breaking) // begin in the // middle end-line \\ end-paragraph \\ \subsection{footnotes} footnotes\footnote{footnote 1 for your pleasure} should be properly // numbered.\footnote{footnote 2} Does it not seem to be\footnote{a word with very many meanings} so? This\footnote{footnote 4} is bad practice \subsubsection{\footnote{footnote} in heading} text \subsection{section breaking} Paragraph followed by adjacent \subsubsection{headline} Paragraph in between \subsubsection{another headline} Some text \subsubsection{headline followed by} normal text \subsubsection{two adjacent} \subsubsection{headlines} Paragraph followed by \begin{center}\rule{0.5\textwidth}{0.02em}\end{center} section marker \begin{center}\rule{0.5\textwidth}{0.03em}\end{center} both section markers here are adjacent \begin{center}\rule{0.5\textwidth}{0.04em}\end{center} Some text \begin{center}\rule{0.5\textwidth}{0.05em}\end{center} Once more \begin{center}\rule{0.5\textwidth}{0.06em}\end{center} \begin{center}\rule{0.5\textwidth}{0.07em}\end{center} \subsection{preformatted} {{{Block}}} Another block: \begin{alltt} content content content \end{alltt} And then: \begin{alltt} content content content [empty line above] \end{alltt} followed by an explanation. \begin{itemize} \item this one is within a list, I reckon: \begin{alltt} /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" \end{alltt} \begin{itemize} \item embedded list and literal block: \begin{alltt} foo /bar/ \end{alltt} \end{itemize} \end{itemize} \subsection{special characters} Hello World!\texttrademark{} is a common program \ensuremath{\rightarrow{}} stupid. stupid \ensuremath{\leftarrow{}} me, also. This is a range in January--February of 2004. There are some special considerations---such as the em dash here. How many test do you need for changing a light bulb?---I guess 6--8. \begin{quotation} ---blockquote ends this thing--- \end{quotation} \end{document} stx2any/regression/abbrev.param0000644000175000017500000000004410423671243020567 0ustar pkalliokpkalliok00000000000000--numbering on --no-emdash-separate stx2any/regression/link-abbrev-toc.html0000644000175000017500000000127710423671243022162 0ustar pkalliokpkalliok00000000000000 foo
    bar
    baz
    quux
    buux
    zuux

    foo

    bar

    baz

    quux

    buux

    zuux

    Oh yes, go back to foo. stx2any/regression/link-abbrev-toc.test0000644000175000017500000000011510423671243022163 0ustar pkalliokpkalliok00000000000000 ! foo !! bar !!! baz ! quux !! buux ! zuux Oh yes, go back to [foo]. stx2any/regression/comment-lines.stripped0000644000175000017500000000034510423671243022636 0ustar pkalliokpkalliok00000000000000--title: The Title --doc_id: metadata-test --author: Author Name --date: day/month/year --section: 8 --language: english --char_coding: ascii -- --! w_title -- introduction -- --This is the "w_date" version, written by w_author. stx2any/regression/markup.man0000644000175000017500000000301110471044066020275 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" This should eventually end up in the ingress. Thank you! .RS 8 This should be the next thing in the ingress. ? .RE .SH NAME foo \- a useful program .br \- a regression test document .PP foo begins .br foo in action, this is a link to heaven\& .SM [1] \&. .br foo ends .br \& .SM [1] \& http://heaven/ .br .PP .ce 10000 .PP This should be a centered, .br compact, .br nice list. .br .ce 0 .PP Normal running text, \fBstrong\fP stuff, \fIemphasised\fP stuff, \fCliteral\fP stuff. See this? .PP Google\& .SM [2] \& - named link; \fChttp://www.google.fi/\fP - unnamed link. .br \& .SM [2] \& http://www.google.fi/ .br .RS 8 .PP There are two kinds of common people: .br kind people, and people in common. .br \(em Frank D. Roosevelt,esq. .RE .PP \& .PSPIC "myimage.eps" \& testpackage used .PP Float 1. .PP \(em \(em \(em \(em \(em .PP Nothing here, actually. .PP .SM The first float. .PP \(em \(em \(em \(em \(em .PP Float 2. Please see float 2 for details. .br .PP \(em \(em \(em \(em \(em .PP Nothing here, either. .PP .SM The second float. .PP \(em \(em \(em \(em \(em .PP Float 3. Float 4. Good we had that sorted out, isn't it? .br .PP \(em \(em \(em \(em \(em .PP Well, here is at least something: \& .PSPIC "marine_band.eps" \& .PP .SM The third float. .PP \(em \(em \(em \(em \(em .PP \(em \(em \(em \(em \(em .PP Still nothing. .PP .SM The fourth float. .PP \(em \(em \(em \(em \(em Note: .RS 8 .PP This is a note for your interest. .RE Go slow: .RS 8 .PP This admonition will give gentle words of caution. .RE stx2any/regression/strip.stripped0000644000175000017500000000027610423671243021230 0ustar pkalliokpkalliok00000000000000content content content content content content [empty line above] /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" foo /bar/ stx2any/regression/defn-nest.docbook-xml0000644000175000017500000000463610423671243022342 0ustar pkalliokpkalliok00000000000000

    foo bar baz quux hyvin toimii foo2 bar2 baz2 quux2 [foo3] hakasuluissa meep huonosti toimii foo3 flooz sooz mooz booz dooz klooz foo4 Kiitos foo5 ekkooo tokkoo Ja vielä: foo6 ekkkooo tokkoooo defnlist foo nested defn bar nested defn 2 baz continuation defnlist2 immediate nested defn stuff
    stx2any/regression/table.html0000644000175000017500000000271110423671243020264 0ustar pkalliokpkalliok00000000000000
    Emigration is nice! foo
    Immigration is even nicer! bar
    account name miscellaneous notes
    pkalliok Panu not trustworthy, but a nice fellow overall. Good to get acquainted with.
    atehwa Panu the same person
    root superuser found in every Unix under the sky
    j",
    L J
    `_'

    • still works?
    stx2any/regression/table.test0000644000175000017500000000123610423671243020300 0ustar pkalliokpkalliok00000000000000 w_beg(table, p, c) Emigration is nice! || foo // Immigration is even nicer! || bar // w_end(table) w_beg(table, l, l, p) account || name || miscellaneous notes // ---- pkalliok || Panu || not trustworthy, but a nice fellow overall. Good to get acquainted with. // atehwa || Panu || the same person // root || superuser || found in every Unix under the sky // w_end(table) w_beg(table, r, c, l) j||"||,// L|| ||J// w_bq||_||'// w_end(table) dnl w_beg(listtable, r, p, p) dnl * first row dnl * first row, first item dnl * first row, second item dnl * second row dnl * second row, first item dnl * second row, second item dnl w_end(listtable) - still works? stx2any/regression/underscore.latex0000644000175000017500000000155410423671243021523 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{underscore quoting tests} \author{} \date{} \begin{document} \maketitle \tableofcontents This should receive \emph{emphasis} This \emph{might} not receive \emph{emphasis} This \_ probably should receive \emph{emphasis} Underscores \_f \emph{nested} b\_ and between\_words Continuing \emph{multiple lines} should work \strongemph{Even now} it \emph{should probably} work indeed foobar \emph{empha} not\_empha \emph{can't} foobar \emph{empha} not\_empha \emph{can't} This is line: 20 in file: stdin \begin{quotation} In blockquote, how does an em dash --- even a little one --- work at the beginning of a line? (This has nothing to do with underscores.) \end{quotation} \end{document} stx2any/regression/underscore.param0000644000175000017500000000003210423671243021474 0ustar pkalliokpkalliok00000000000000--quote --quote-me-harder stx2any/regression/slide.html0000644000175000017500000000250010423671243020271 0ustar pkalliokpkalliok00000000000000 slide test

    This is a slide.

    • markup should work ordinarily.
    • nothing special here, either.

    Important points

    This is the second slide.

    stx2any/regression/link-abbrev.html0000644000175000017500000000576210423671243021402 0ustar pkalliokpkalliok00000000000000

    Testing link abbreviations

    First paragraph. It does not have anything weird.

    Second paragraph. It doesn't have anything weird, either. There's just a line that begins with something that looks quite a lot like a [1] block. Do we manage it?
    [1] linkdata

    Okay, now for the real thing. There should be all kinds of links here. See Testing link abbreviations to get a hold of what they all mean. [2].
    [2] This is a longer footnote, possibly spanning multiple lines.

    There are longer links: ftp://ftp.rfc-editor.org/in-notes/rfc1355.txt and friends. The problem with URIs is that you[3] have hard time knowing where they stop. Take for example http://www.plt-scheme.org/: why is the slash included but the colon not[4]? (Another example is http://c2.com/cgi/quickChanges, or http://sange.fi/~atehwa/index.html…)
    [3] the reader
    [4] Don't tell me that properly quoted URI's won't have colons in such positions. People never properly quote URI's, as required by RFC2396.

    Here is also an inline image. Please jump back. I want you to consider an unadored relative link and another.

    Does the old-style footnote[5] work anymore in the presence of link abbreviations[6]?[7]
    [5] such as this one here
    [6] as tested by this file
    [7] And does it work if broken into multiple lines?

    Explicit label (is not guaranteed to work properly)

    How do multiple labels in the same line work? What about Second-label conflicts?

    This is an interesting way to produce a bibliography:

    RFC2396: Uniform Resource Identifies (URI): Generic Syntax (ftp://ftp.rfc-editor.org/in-notes/rfc2396.txt) stx2any/regression/slide.test0000644000175000017500000000045310423671243020311 0ustar pkalliokpkalliok00000000000000title: slide test author: somebody date: ??.??.???? w_slideheader(w_title)dnl w_slidefooter(w_author w_date)dnl w_beg(slide) This is a slide. * markup should work ordinarily. * nothing special here, either. w_end(slide) w_beg(slide) ! Important points This is the second slide. w_end(slide) stx2any/regression/link-abbrev.test0000644000175000017500000000364510423671243021413 0ustar pkalliokpkalliok00000000000000 ! Testing link abbreviations First paragraph. It does not have anything weird. [1] This is a footnote. [2] This is a longer footnote, possibly spanning multiple lines. [3] http://www.ithaka.net/ [4] ftp://ftp.spoogle.com/ [5] mailto:some.email@address.fi [6] img:pictures/zebra [7] Foobar. I just want to show off. [+Second paragraph+]. It doesn't have anything weird, either. There's just a line that begins with something that looks quite a lot like a [linkdata] block. Do we manage it? Okay, now for the real[5] thing. There should be all [kinds of][4] links here. See "[Testing link abbreviations]" to get a hold of what they all mean[http://www.meaning.org/]. [2]. [azimuth] img:http://zooie.org/pict/flounder [RFC1355] ftp://ftp.rfc-editor.org/in-notes/rfc1355.txt There are longer links: [RFC1355] and friends. The problem with URIs[RFC2396] is that you[the reader] have hard time knowing where they stop. Take for example http://www.plt-scheme.org/: why is the slash included but [the colon not][note1]? (Another example is http://c2.com/cgi/quickChanges, or http://sange.fi/~atehwa/index.html...) [note1] Don't tell me that properly quoted URI's won't have colons in such positions. People never properly quote URI's, as required by [RFC2396]. Here is also an [inline image][6]. Please jump back[Second paragraph]. I want you to consider an [unadored relative link][./foo.html] and another[../index.html]. Does the old-style footnote[[ such as this one here ]] work anymore in the presence of link abbreviations[[-as tested by this file-]]?[[-And does it work if broken into multiple lines?-]] !! [+Explicit label+] (is not guaranteed to work properly) How do [+multiple labels+] in the same line [+work+]? What about [+Second-label conflicts+]? ---- This is an interesting way to produce a bibliography: [+RFC2396+]: Uniform Resource Identifies (URI): Generic Syntax (ftp://ftp.rfc-editor.org/in-notes/rfc2396.txt) stx2any/regression/link-abbrev-bug.html0000644000175000017500000000044310423671243022144 0ustar pkalliokpkalliok00000000000000 A

    BB

    C stx2any/regression/link-abbrev-bug.test0000644000175000017500000000001010423671243022145 0ustar pkalliokpkalliok00000000000000A B C stx2any/regression/change-suffix.gather_stx_titles0000644000175000017500000000001710423671243024511 0ustar pkalliokpkalliok00000000000000-f test -t stx stx2any/regression/link-abbrev-bug.latex0000644000175000017500000000042210423671243022312 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle \tableofcontents A BB C \end{document} stx2any/regression/link-abbrev-bug.param0000644000175000017500000000010110423671243022267 0ustar pkalliokpkalliok00000000000000--link-abbrevs --sed-preprocessor regression/link-abbrev-bug.sed stx2any/regression/weird.gather_stx_titles0000644000175000017500000000002210423671243023070 0ustar pkalliokpkalliok00000000000000-p regr -f e.test stx2any/regression/link-abbrev-toc.latex0000644000175000017500000000074110423671243022326 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle \tableofcontents \section{\label{foo}foo} \subsection{\label{bar}bar} \subsubsection{\label{baz}baz} \section{\label{quux}quux} \subsection{\label{buux}buux} \section{\label{zuux}zuux} Oh yes, go back to foo (\pageref{foo}). \end{document} stx2any/regression/link-abbrev-toc.param0000644000175000017500000000004610423671243022307 0ustar pkalliokpkalliok00000000000000--link-abbrevs --table-of-contents on stx2any/regression/link-abbrev-toc.docbook-xml0000644000175000017500000000121410423671243023423 0ustar pkalliokpkalliok00000000000000

    <Anchor id="foo"/>foo <Anchor id="bar"/>bar <Anchor id="baz"/>baz <Anchor id="quux"/>quux <Anchor id="buux"/>buux <Anchor id="zuux"/>zuux Oh yes, go back to foo.
    stx2any/regression/table.docbook-xml0000644000175000017500000000276710423671243021551 0ustar pkalliokpkalliok00000000000000
    Emigration is nice! foo Immigration is even nicer! bar account name miscellaneous notes pkalliok Panu not trustworthy, but a nice fellow overall. Good to get acquainted with. atehwa Panu the same person root superuser found in every Unix under the sky j", L J `_' still works?
    stx2any/regression/change-suffix.titles0000644000175000017500000000176310423671243022272 0ustar pkalliokpkalliok00000000000000define(`@w_file_exists_regression/abbrev.stx', t)dnl define(`@w_file_exists_regression/crossref.stx', t)dnl define(`@w_file_exists_regression/defn-nest.stx', t)dnl define(`@w_file_exists_regression/link-abbrev-bug.stx', t)dnl define(`@w_file_exists_regression/link-abbrev.stx', t)dnl define(`@w_file_exists_regression/link-abbrev-toc.stx', t)dnl define(`@w_file_exists_regression/list.stx', t)dnl define(`@w_file_exists_regression/markup.stx', t)dnl define(`@w_file_exists_regression/metadata.stx', t)dnl define(`@w_file_exists_regression/slide.stx', t)dnl define(`@w_file_exists_regression/table.stx', t)dnl define(`@w_file_exists_regression/underscore.stx', t)dnl define(`@w_filename_of_crossref-test', `regression/crossref.stx')dnl define(`@w_title_of_'`regression/metadata.stx', `The Title')dnl define(`@w_filename_of_metadata-test', `regression/metadata.stx')dnl define(`@w_title_of_'`regression/slide.stx', `slide test')dnl define(`@w_title_of_'`regression/underscore.stx', `underscore quoting tests')dnl stx2any/regression/abbrev.docbook-xml0000644000175000017500000001346210423671243021715 0ustar pkalliokpkalliok00000000000000
    1 headline 1 1.1 headline 2 1.1.1 headline 3 1.1.1.1 headline 4 1.2 miscellaneous inline end of line, quoted stuff end of line, emphasised stuff end of line, strongly emphasised stuff end of line, literal-formatted stuff. quoted stuff, at the beginning of linethis is a footnote /emphasised / not, another try; nested emphasis for kiddies-- literal-formatted stuff spanning multiple lines, emphasis improperly nested emphasis markers spanning multiple lines for fun very long quoted string with /inner/ emphasis and other way *around* for them if you please and goodies to try (thank you) Emphasis within quotes Quotes within emphasis Strongem within quotes Quotes within strongem Literal within quotes Quotes within literal Literal ''within'' emphasis Emphasis _within_ literal Literal ''within'' strongem Strongem *within* literal Quoted "quotes" for you Quoted _emphasis_ for you Quoted *strongem* for you Quoted ''litfmt'' for you unmatched end-of-emphasis/ marker "Different * emphasis / characters "" out '' of ''' context '''' j proper /path/to/file and its literal cousin, /path/to/file Some */random mixed** emphasis mark*ers and a footnote that has multiple lines *strongemph*broken by* char /emphasis/broken by/ char literal'not broken by char ''literal''broken by'' char literal'with quotes not broken anymore literal'spanning multiple lines not broken by char *strongemph * broken by* space-sep char /emphasis / broken by/ space-sep char One char c emph One char c strongemph (underscores) emphasis type 1 an underscore _ by itself; between_words double _nested emphasis for_ convenience This _should_not_ work (line breaking) // begin in the // middle end-line end-paragraph 1.3 footnotes footnotesfootnote 1 for your pleasure should be properly // numbered.footnote 2 Does it not seem to bea word with very many meanings so? Thisfootnote 4 is bad practice 1.3.1 <Footnote><Para>footnote</Para></Footnote> in heading text 1.4 section breaking Paragraph followed by adjacent 1.4.1 headline Paragraph in between 1.4.2 another headline Some text 1.4.3 headline followed by normal text 1.4.4 two adjacent 1.4.5 headlines Paragraph followed by — — — section marker — — — both section markers here are adjacent — — — Some text — — — — — Once more — — — — — — — — — — 1.5 preformatted {{{Block}}} Another block: content content content And then: content content content [empty line above] followed by an explanation. this one is within a list, I reckon: /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" embedded list and literal block: foo /bar/ 1.6 special characters Hello World!™ is a common program → stupid. stupid ← me, also. This is a range in January–February of 2004. There are some special considerations—such as the em dash here. How many test do you need for changing a light bulb?—I guess 6–8.
    —blockquote ends this thing—
    stx2any/regression/block.stripped0000644000175000017500000000606410423671243021162 0ustar pkalliokpkalliok00000000000000 content content content content content content [empty line above] /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" foo /bar/ stx2any/regression/crossref.man0000644000175000017500000000056510423671243020637 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" This goes into the ingress .br .PP This test is \(co 1851 E. A. Poe. \(em I think. Making smooth transitions is hard work. It's not worth hardening the hard; you should look into means of making things go more smoothly. .PP This goes into the ingress .PP Thank you for listening.\|.\|. the percussions. .PP smooth .br hard .br hard .br percussions .br stx2any/regression/link-abbrev.docbook-xml0000644000175000017500000000603410423671243022645 0ustar pkalliokpkalliok00000000000000
    <Anchor id="Testing.link.abbreviations"/>Testing link abbreviations First paragraph. It does not have anything weird. Second paragraph. It doesn't have anything weird, either. There's just a line that begins with something that looks quite a lot like a linkdata block. Do we manage it? Okay, now for the real thing. There should be all kinds of links here. See Testing link abbreviations to get a hold of what they all mean. This is a longer footnote, possibly spanning multiple lines.. There are longer links: ftp://ftp.rfc-editor.org/in-notes/rfc1355.txt and friends. The problem with URIs is that youthe reader have hard time knowing where they stop. Take for example http://www.plt-scheme.org/: why is the slash included but the colon notDon't tell me that properly quoted URI's won't have colons in such positions. People never properly quote URI's, as required by RFC2396.? (Another example is http://c2.com/cgi/quickChanges, or http://sange.fi/~atehwa/index.html…) Here is also an inline image . Please jump back. I want you to consider an unadored relative link and another. Does the old-style footnotesuch as this one here work anymore in the presence of link abbreviationsas tested by this file?And does it work if broken into multiple lines? <Anchor id="w.autolabel.Explicit.label...is.not.guaranteed.to.work.properly."/><Anchor id="Explicit.label"/>Explicit label (is not guaranteed to work properly) How do multiple labels in the same line work? What about Second-label conflicts? — — — This is an interesting way to produce a bibliography: RFC2396: Uniform Resource Identifies (URI): Generic Syntax (ftp://ftp.rfc-editor.org/in-notes/rfc2396.txt)
    stx2any/regression/list.html0000644000175000017500000000304110423671243020145 0ustar pkalliokpkalliok00000000000000
    • a
    • b
    • c
    • d
      • e
        1. f
        2. g # foo
      • inner
        1. zoo
        2. boo
        1. new list
        2. item2

        quote?

        quote?

      quote?

    — interlude —

    • one
    • two
    • three in a row for a cow
    • four
      this is so
      as definitions go too low

      final blow

    • five

      it's alive

      consider quote
      back we go
    • list intercept
      this is the term
      show some respect
      it is so firm
    • the problem's not here anymore
    term one
    • lists are fun
    the fun's begun
    term two
    definitions, too! another for you.

    They can have paragraphs

    term three a
    term three b
    a tree is a tree
    be or not to be?
    • what's happening to me?
    • be or not to be?
    • what can you say?
    • what's for the delay?
    • let's play

    — interlude 2 —

    • foo foo2
      • bar bar2
    • baz baz2
      • quux quux2
      • fooox [1] fooox2 [2] fooox3
        • koe
          [1] footnote?
          [2] footnote?
    stx2any/regression/list.test0000644000175000017500000000210110423671243020154 0ustar pkalliokpkalliok00000000000000 - a - b * c * d * e # f # g # foo * inner # zoo # boo # new list # item2 quote? quote? quote? -- interlude -- - one - two - three in a row for a cow - four this is so:: as definitions go too low final blow - five it's alive consider quote back we go - list intercept this is the term:: show some respect it is so firm - the problem's not here anymore term one:: - lists are fun the fun's begun term two:: definitions, too! another for you. They can have paragraphs term three a:: term three b:: a tree is a tree // be or not to be? - what's happening to me? - be or not to be? - what can you say? - what's for the delay? - let's play -- interlude 2 -- - foo foo2 - bar bar2 - baz baz2 - quux quux2 - fooox [[ footnote? ]] fooox2 [[ footnote? ]] fooox3 - koe stx2any/regression/list.latex0000644000175000017500000000371110423671243020322 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle \tableofcontents \begin{itemize} \item a \item b \end{itemize} \begin{itemize} \item c \item d \begin{itemize} \item e \begin{enumerate} \item f \item g \# foo \end{enumerate} \item inner \begin{enumerate} \item zoo \item boo \end{enumerate} \begin{enumerate} \item new list \item item2 \end{enumerate} \begin{quotation} quote? \end{quotation} quote? \end{itemize} quote? \end{itemize} --- interlude --- \begin{itemize} \item one \item two \item three in a row for a cow \item four \begin{description} \item[{this is so}] as definitions go too low \end{description} final blow \item five it's alive \begin{quotation} consider quote \end{quotation} back we go \end{itemize} \begin{itemize} \item list intercept \begin{description} \item[{this is the term}] show some respect \end{description} it is so firm \item the problem's not here anymore \end{itemize} \begin{description} \item[{term one}] \begin{itemize} \item lists are fun \end{itemize} the fun's begun \item[{term two}] definitions, too! another for you. They can have paragraphs \item[{term three a}] \item[{term three b}] a tree is a tree \\ be or not to be? \begin{itemize} \item what's happening to me? \end{itemize} \begin{itemize} \item be or not to be? \end{itemize} \begin{itemize} \item what can you say? \end{itemize} \end{description} \begin{itemize} \item what's for the delay? \end{itemize} \begin{itemize} \item let's play \end{itemize} --- interlude 2 --- \begin{itemize} \item foo foo2 \begin{itemize} \item bar bar2 \end{itemize} \end{itemize} \begin{itemize} \item baz baz2 \begin{itemize} \item quux quux2 \item fooox \footnote{ footnote?} fooox2 \footnote{footnote? } fooox3 \begin{itemize} \item koe \end{itemize} \end{itemize} \end{itemize} \end{document} stx2any/regression/list.param0000644000175000017500000000002710423671243020302 0ustar pkalliokpkalliok00000000000000--link-abbrevs --quote stx2any/regression/comment-lines.strip_stx0000644000175000017500000000003710423671243023041 0ustar pkalliokpkalliok00000000000000-c -- regression/metadata.test stx2any/regression/link-abbrev-toc.man0000644000175000017500000000022710423671243021763 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" foo .br bar .br baz .br quux .br buux .br zuux .br .SH foo .SS bar .PP .B baz .SH quux .SS buux .SH zuux .PP Oh yes, go back to foo. stx2any/regression/markup.latex0000644000175000017500000000341610471044066020650 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \usepackage{url} \usepackage{graphicx} \begin{document} \maketitle \emph{a regression test document}\\ This should eventually end up in the ingress. Thank you! \begin{abstract} This should be the next thing in the ingress. ? \end{abstract}\tableofcontents foo --- a useful program \\ foo begins \\ foo in action, this is a link to heaven\footnote{\url{http://heaven/}}. \\ foo ends \begin{center}This should be a centered,\\ compact,\\ nice list.\\ \end{center} Normal running text, \strongemph{strong} stuff, \emph{emphasised} stuff, \litfmt{literal} stuff. See this? Google\footnote{\url{http://www.google.fi/}} - named link; \url{http://www.google.fi/} - unnamed link. \begin{quotation} There are two kinds of common people: \\ kind people, and people in common. \\ --- Frank D. Roosevelt,esq. \end{quotation} \includegraphics{myimage.eps} testpackage used Float 1. \begin{center}\rule{0.5\textwidth}{0.05em}\end{center} Nothing here, actually. The first float. \begin{center}\rule{0.5\textwidth}{0.05em}\end{center} Float 2. \begin{figure}[htb]Nothing here, either. \caption{\label{f2}The second float.} \end{figure}Please see float 2 (\pageref{f2}) for details. Float 3. \begin{figure}[tbp]Well, here is at least something: \includegraphics{marine_band.eps} \caption{The third float.} \end{figure}Float 4. \marginpar{Still nothing. \\ The fourth float. }Good we had that sorted out, isn't it? Note: \begin{quotation} This is a note for your interest. \end{quotation} Go slow: \begin{quotation} This admonition will give gentle words of caution. \end{quotation} \end{document} stx2any/regression/slide.docbook-xml0000644000175000017500000000164210423671243021551 0ustar pkalliokpkalliok00000000000000
    slide test somebody slide test — — — This is a slide. markup should work ordinarily. nothing special here, either. — — — somebody ??.??.???? — — — — — slide test — — — Important points This is the second slide. — — — somebody ??.??.???? — — — — —
    stx2any/regression/prefix-strip.titles0000644000175000017500000000151110423671243022166 0ustar pkalliokpkalliok00000000000000define(`@w_file_exists_abbrev.test', t)dnl define(`@w_file_exists_crossref.test', t)dnl define(`@w_file_exists_defn-nest.test', t)dnl define(`@w_file_exists_link-abbrev-bug.test', t)dnl define(`@w_file_exists_link-abbrev.test', t)dnl define(`@w_file_exists_link-abbrev-toc.test', t)dnl define(`@w_file_exists_list.test', t)dnl define(`@w_file_exists_markup.test', t)dnl define(`@w_file_exists_metadata.test', t)dnl define(`@w_file_exists_slide.test', t)dnl define(`@w_file_exists_table.test', t)dnl define(`@w_file_exists_underscore.test', t)dnl define(`@w_filename_of_crossref-test', `crossref.test')dnl define(`@w_title_of_'`metadata.test', `The Title')dnl define(`@w_filename_of_metadata-test', `metadata.test')dnl define(`@w_title_of_'`slide.test', `slide test')dnl define(`@w_title_of_'`underscore.test', `underscore quoting tests')dnl stx2any/regression/markup.html0000644000175000017500000000401510471044066020473 0ustar pkalliokpkalliok00000000000000 a regression test document
    This should eventually end up in the ingress. Thank you!
    This should be the next thing in the ingress. ?
    foo — a useful program

    foo begins
    foo in action, this is a link to heaven.
    foo ends

    This should be a centered,
    compact,
    nice list.

    Normal running text, strong stuff, emphasised stuff, literal stuff. See this?

    Google - named link; http://www.google.fi/ - unnamed link.

    There are two kinds of common people:
    kind people, and people in common.
    — Frank D. Roosevelt,esq.

    A picture of a kaenggrakieppura posing testpackage used

    Float 1.

    Nothing here, actually.

    The first float.

    Float 2. Please see float 2 for details.
    Nothing here, either.

    The second float.

    Float 3.

    Well, here is at least something: some drunken marines trying to produce music

    The third float.

    Float 4.
    Still nothing.

    The fourth float.

    Good we had that sorted out, isn't it? Note:

    This is a note for your interest.

    Go slow:

    This admonition will give gentle words of caution.

    stx2any/regression/markup.test0000644000175000017500000000356510471044066020517 0ustar pkalliokpkalliok00000000000000w_define_div(anglais)dnl w_define_env(foo,dnl `w_beg_para`'foo begins w_linebr`'w_nl',dnl `w_linebr`'w_nl`'foo ends`'w_nl')dnl w_def_in_fmt(html, Thank, Th``ank'')dnl w_man_desc(foo, a useful program) w_man_desc(a regression test document) w_beg(foo) foo in action, this is a link to w_link(http://heaven/, heaven). w_end(foo) w_begdiv(anglais)dnl This should eventually end up in the ingress. w_enddiv(anglais)dnl w_begdiv(ingr)dnl w_dumpdiv(anglais)dnl Thank you! w_enddiv(ingr)dnl w_beg(center) w_beg(compactlist) This should be a centered, compact, nice list. w_end(compactlist) w_end(center) w_beg(abstract) This should be the next thing in the ingress. ? w_end(abstract) Normal running text, w_strong(strong) stuff, w_emph(emphasised) stuff, w_literal(literal) stuff. w_beg(ifeq, foo, foo) See this? w_beg(ifeq, foo, bar) see this not? w_end(ifeq) w_end(ifeq) w_link(http://www.google.fi/, Google) - named link; w_url(http://www.google.fi/) - unnamed link. w_beg(citation, Frank D. Roosevelt, esq.) There are two kinds of common people: // kind people, and people in common. w_end(citation) w_img(myimage, A picture of a kaenggrakieppura posing) w_use(regression/testpackage)dnl w_use(regression/testpackage)dnl Float 1. w_beg(float, hnfm, The first float.) Nothing here, actually. w_end(float) Float 2. w_beg(float, nfm, w_label(f2, The second float.)) Nothing here, either. w_end(float) Please see w_refer(f2, float 2) for details. Float 3. w_beg(float, fmnh, The third float.) Well, here is at least something: w_img(marine_band, some drunken marines trying to produce music) w_end(float) Float 4. w_beg(float, mnh, The fourth float.) Still nothing. w_end(float) Good we had that sorted out, isn't it? w_beg(admonition, Note) This is a note for your interest. w_end(admonition) w_beg(admonition, Go slow) This admonition will give gentle words of caution. w_end(admonition) stx2any/regression/defn-nest.html0000644000175000017500000000174710423671243021070 0ustar pkalliokpkalliok00000000000000
    foo
    • bar
    • baz
    • quux

    hyvin toimii

    foo2
    • bar2
    • baz2
    • quux2
    [foo3] hakasuluissa
    • meep

    huonosti toimii

    foo3
    1. flooz
    2. sooz
    1. mooz
    2. booz
      1. dooz
      2. klooz
    foo4
    Kiitos
    foo5
    • ekkooo
    • tokkoo

    Ja vielä:

    foo6
    • ekkkooo
    • tokkoooo
    defnlist

    foo

    nested defn
    bar
    nested defn 2
    baz

    continuation

    defnlist2
    immediate nested defn
    stuff
    stx2any/regression/testpackage.m40000644000175000017500000000002110423671243021034 0ustar pkalliokpkalliok00000000000000testpackage used stx2any/regression/defn-nest.test0000644000175000017500000000062710423671243021077 0ustar pkalliokpkalliok00000000000000 foo:: - bar - baz - quux hyvin toimii foo2:: - bar2 - baz2 - quux2 [foo3] hakasuluissa:: - meep huonosti toimii foo3:: # flooz # sooz # mooz # booz # dooz # klooz foo4:: Kiitos foo5:: - ekkooo - tokkoo Ja vielä: foo6:: - ekkkooo - tokkoooo defnlist:: foo nested defn:: bar nested defn 2:: baz continuation defnlist2:: immediate nested defn:: stuff stx2any/regression/underscore.html0000644000175000017500000000167610423671243021357 0ustar pkalliokpkalliok00000000000000 underscore quoting tests

    underscore quoting tests

    This should receive emphasis This might not receive emphasis This _ probably should receive emphasis Underscores _f nested b_ and between_words

    Continuing multiple lines should work

    Even now it should probably work indeed

    foobar empha not_empha can't foobar empha not_empha can't

    This is line: 20 in file: stdin

    In blockquote, how does an em dash — even a little one — work at the beginning of a line? (This has nothing to do with underscores.)

    stx2any/regression/underscore.test0000644000175000017500000000106010423671243021355 0ustar pkalliokpkalliok00000000000000title: underscore quoting tests char_coding: latin1 This should receive _emphasis_ This w_emph(might) not receive _emphasis_ This _ probably should receive _emphasis_ Underscores _f _nested_ b_ and between_words Continuing _multiple lines_ should work w_strong(Even now) it _should probably_ work indeed foobar _empha_ not_empha _can't_ `foobar' _empha_ not_empha _can't_ This is line: __line__ in file: __file__ In blockquote, how does an em dash -- even a little one -- work at the beginning of a line? (This has nothing to do with underscores.) stx2any/regression/run-tests0000755000175000017500000000166410423671243020207 0ustar pkalliokpkalliok00000000000000#!/bin/sh #This file is under the license in ../LICENSE. export PAPERSIZE=a4 failed="" run_test() { param=regression/$1.param test=regression/$1.test ./scripts/stx2any `test -f $param && cat $param` -T $2 $test | \ diff -u regression/$1.$2 - || failed="$failed $1($2)" } for i in regression/*.test; do echo Running $i ... base=`basename $i .test` for fmt in html man latex docbook-xml; do run_test $base $fmt done done for i in regression/*.strip_stx; do echo Running $i ... base=`basename $i .strip_stx` ./scripts/strip_stx `cat $i` | \ diff -u regression/$base.stripped - || failed="$failed strip_stx($base)" done for i in regression/*.gather_stx_titles; do echo Running $i ... base=`basename $i .gather_stx_titles` ./scripts/gather_stx_titles `cat $i` regression/*.test | \ diff -u regression/$base.titles - || failed="$failed gather_stx_titles($base)" done test -n "$failed" && echo Failed tests: $failed test -z "$failed" stx2any/regression/markup.docbook-xml0000644000175000017500000000503010471044066021743 0ustar pkalliokpkalliok00000000000000
    a regression test document This should eventually end up in the ingress. Thank you! This should be the next thing in the ingress. ? foo — a useful program foo begins foo in action, this is a link to heaven. foo ends This should be a centered, compact, nice list. Normal running text, strong stuff, emphasised stuff, literal stuff. See this? Google - named link; http://www.google.fi/ - unnamed link.
    Frank D. Roosevelt,esq.There are two kinds of common people: kind people, and people in common.
    A picture of a kaenggrakieppura posing testpackage used Float 1. — — — — — Nothing here, actually. The first float. — — — — — Float 2.
    Nothing here, either. The second float.
    Please see float 2 for details. Float 3.
    Well, here is at least something: some drunken marines trying to produce music The third float.
    Float 4.
    Still nothing. The fourth float.
    Good we had that sorted out, isn't it? This is a note for your interest. Go slow:This admonition will give gentle words of caution.
    stx2any/regression/block.strip_stx0000644000175000017500000000004310423671243021356 0ustar pkalliokpkalliok00000000000000-B regression/abbrev.test stx2any/regression/slide.man0000644000175000017500000000065310423671243020107 0ustar pkalliokpkalliok00000000000000.TH "slide test" "" "??.??.????" "somebody" .PP slide test .PP \(em \(em \(em .PP This is a slide. .RS 4 .IP \(bu 4 \&markup should work ordinarily. .IP \(bu 4 \¬hing special here, either. .RE .PP \(em \(em \(em .PP somebody ??.??.???? .PP \(em \(em \(em \(em \(em .PP slide test .PP \(em \(em \(em .SH Important points .PP This is the second slide. .PP \(em \(em \(em .PP somebody ??.??.???? .PP \(em \(em \(em \(em \(em stx2any/regression/defn-nest.latex0000644000175000017500000000255410423671243021236 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle \tableofcontents \begin{description} \item[{foo}] \begin{itemize} \item bar \item baz \item quux \end{itemize} hyvin toimii \item[{foo2}] \end{description} \begin{itemize} \item bar2 \item baz2 \item quux2 \end{itemize} \begin{description} \item[{[foo3] hakasuluissa}] \end{description} \begin{itemize} \item meep \end{itemize} huonosti toimii \begin{description} \item[{foo3}] \begin{enumerate} \item flooz \item sooz \end{enumerate} \end{description} \begin{enumerate} \item mooz \item booz \begin{enumerate} \item dooz \item klooz \end{enumerate} \end{enumerate} \begin{description} \item[{foo4}] Kiitos \end{description} \begin{description} \item[{foo5}] \end{description} \begin{itemize} \item ekkooo \item tokkoo \end{itemize} Ja vielä: \begin{description} \item[{foo6}] \end{description} \begin{itemize} \item ekkkooo \item tokkoooo \end{itemize} \begin{description} \item[{defnlist}] foo \begin{description} \item[{nested defn}] bar \item[{nested defn 2}] baz \end{description} continuation \item[{defnlist2}] \begin{description} \item[{immediate nested defn}] stuff \end{description} \end{description} \end{document} stx2any/regression/strip.strip_stx0000644000175000017500000000002710423671243021427 0ustar pkalliokpkalliok00000000000000regression/abbrev.test stx2any/regression/metadata.man0000644000175000017500000000024510423671243020564 0ustar pkalliokpkalliok00000000000000.TH "The Title" "8" "day/month/year" "Author Name" .hla en .SH The Title \(em introduction .PP This is the \(lqday/month/year\(rq version, written by Author Name. stx2any/regression/list.docbook-xml0000644000175000017500000000643410423671243021430 0ustar pkalliokpkalliok00000000000000
    a b c d e f g # foo inner zoo boo new list item2
    quote?
    quote?     quote?     — interlude — one two three in a row for a cow four this is so as definitions go too low final blow five it's alive
    consider quote
    back we go     list intercept this is the term show some respect it is so firm the problem's not here anymore term one lists are fun the fun's begun term two definitions, too! another for you. They can have paragraphs term three a term three b a tree is a tree be or not to be? what's happening to me? be or not to be? what can you say? what's for the delay? let's play — interlude 2 — foo foo2 bar bar2 baz baz2 quux quux2 fooox footnote? fooox2 footnote? fooox3 koe
    stx2any/regression/abbrev.html0000644000175000017500000001313310423671243020436 0ustar pkalliokpkalliok00000000000000 1 headline 1
    1.1 headline 2
    1.1.1 headline 3
    1.1.1.1 headline 4
    1.2 miscellaneous inline
    1.3 footnotes
    1.3.1 [8] in heading
    1.4 section breaking
    1.4.1 headline
    1.4.2 another headline
    1.4.3 headline followed by
    1.4.4 two adjacent
    1.4.5 headlines
    1.5 preformatted
    1.6 special characters

    1 headline 1

    1.1 headline 2

    1.1.1 headline 3

    1.1.1.1 headline 4

    1.2 miscellaneous inline

    end of line, quoted stuff end of line, emphasised stuff end of line, strongly emphasised stuff end of line, literal-formatted stuff.

    quoted stuff, at the beginning of line[1] /emphasised / not, another try; nested emphasis for kiddies-- literal-formatted stuff
    spanning multiple lines    , emphasis improperly nested emphasis markers spanning multiple lines for fun
    [1] this is a footnote

    very long quoted string with /inner/ emphasis and other way *around* for them if you please and goodies to try (thank you)

    Emphasis within quotes Quotes within emphasis Strongem within quotes Quotes within strongem Literal within quotes Quotes within literal Literal ''within'' emphasis Emphasis _within_ literal Literal ''within'' strongem Strongem *within* literal Quoted "quotes" for you Quoted _emphasis_ for you Quoted *strongem* for you Quoted ''litfmt'' for you

    unmatched end-of-emphasis/ marker "Different * emphasis / characters "" out '' of ''' context '''' j

    proper /path/to/file and its literal cousin, /path/to/file

    Some */random mixed** emphasis mark*ers [2]
    [2] and a footnote that has multiple lines

    *strongemph*broken by* char /emphasis/broken by/ char literal'not broken by char ''literal''broken by'' char

    literal'with quotes not broken anymore

    literal'spanning multiple lines not broken by char

    *strongemph * broken by* space-sep char /emphasis / broken by/ space-sep char One char c emph One char c strongemph

    (underscores)

    emphasis type 1 an underscore _ by itself; between_words double _nested emphasis for_ convenience This _should_not_ work

    (line breaking)

    // begin in the // middle end-line
    end-paragraph

    1.3 footnotes

    footnotes[3] should be properly // numbered.[4] Does it not seem to be[5] so?
    [3] footnote 1 for your pleasure
    [4] footnote 2
    [5] a word with very many meanings

    This[6] is bad practice

    1.3.1 [7] in heading


    [6] footnote 4
    [7] footnote
    [8] footnote

    text

    1.4 section breaking

    Paragraph followed by adjacent

    1.4.1 headline

    Paragraph in between

    1.4.2 another headline

    Some text

    1.4.3 headline followed by

    normal text

    1.4.4 two adjacent

    1.4.5 headlines

    Paragraph followed by

    section marker

    both section markers here are adjacent

    Some text

    Once more

    1.5 preformatted

    {{{Block}}}

    Another block: 

    content
 content
  content

    And then: 

      content
 content

content [empty line above]
    followed by an explanation.
    • this one is within a list, I reckon: 
      
 /emphasis/
  *strong emphasis*
   line breaking //
    "quoted text" AFAIK

 multi-"line
   span stuff"
      • embedded list and literal block: 
        foo /bar/

    1.6 special characters

    Hello World!™ is a common program → stupid. stupid ← me, also.

    This is a range in January–February of 2004. There are some special considerations—such as the em dash here. How many test do you need for changing a light bulb?—I guess 6–8.

    —blockquote ends this thing—

    stx2any/regression/abbrev.test0000644000175000017500000000604710423671243020457 0ustar pkalliokpkalliok00000000000000 ! headline 1 !! headline 2 !!! headline 3 !!!! headline 4 !! miscellaneous inline end of line, "quoted stuff" end of line, /emphasised stuff/ end of line, *strongly emphasised stuff* end of line, ''literal-formatted stuff''. "quoted stuff", at the beginning of line[[ this is a footnote ]] /emphasised / not, /another try/; /nested *emphasis* for kiddies/-- ''literal-formatted stuff // spanning multiple lines'', /emphasis/ improperly /nested *emphasis markers/ spanning multiple lines* for fun very "long quoted string with */inner/ emphasis* and other way /*around* for them/ if you please and goodies" to try (*thank you*) Emphasis "_within_" quotes Quotes _"within"_ emphasis Strongem "*within*" quotes Quotes *"within"* strongem Literal "''within''" quotes Quotes ''"within"'' literal Literal _''within''_ emphasis Emphasis ''_within_'' literal Literal *''within''* strongem Strongem ''*within*'' literal Quoted `"'quotes" for you Quoted `_'emphasis_ for you Quoted `*'strongem* for you Quoted '`''litfmt'' for you unmatched end-of-emphasis/ marker "Different * emphasis / characters "" out '' of ''' context '''' j proper /path/to/file and its literal cousin, ''/path/to/file'' Some */random mixed** "/emphasis"/ mark*ers [[ and a footnote that /has multiple lines/ ]] *strongemph*broken by* char /emphasis/broken by/ char ''literal'not broken by'' char ''literal''broken by'' char ''literal'with quotes'' `not broken anymore' ''literal'spanning multiple lines'' not broken by char *strongemph * broken by* space-sep char /emphasis / broken by/ space-sep char One char /c/ emph One char *c* strongemph (underscores) _emphasis_ type 1 an underscore _ by _itself_; between_words double _nested _emphasis_ for_ convenience This _should_not_ work (line breaking) // begin in the // middle end-line // end-paragraph // !! footnotes footnotes[[ footnote 1 for your pleasure ]] should be properly // numbered.[[ footnote 2 ]] Does it not seem to be[[ a word with very many meanings ]] so? This[[ footnote 4 ]] is bad practice !!! [[ footnote ]] in heading text !! section breaking Paragraph followed by adjacent !!! headline Paragraph in between !!! another headline Some text !!! headline followed by normal text !!! two adjacent !!! headlines Paragraph followed by -- section marker --- both section markers here are adjacent ---- Some text ----- Once more ------ ------- !! preformatted {{{Block}}} Another block: {{{ content content content }}} And then: {{{ content content content [empty line above] }}} followed by an explanation. - this one is within a list, I reckon: {{{ /emphasis/ *strong emphasis* line breaking // "quoted text" AFAIK multi-"line span stuff" }}} - embedded list and literal block: {{{ foo /bar/ }}} !! special characters Hello World!(tm) is a common program -> stupid. stupid <- me, also. This is a range in January--February of 2004. There are some special considerations -- such as the em dash here. How many test do you need for changing a light bulb? -- I guess 6--8. -- blockquote ends this thing -- stx2any/regression/table.man0000644000175000017500000000074310423671243020076 0ustar pkalliokpkalliok00000000000000.TH "" "" "" "" \& .TS l c . T{ \&Emigration is nice! \& T} foo T{ \&Immigration is even nicer! \& T} bar \& .TE \& .TS l l l . account name T{ \& miscellaneous notes \& T} _ pkalliok Panu T{ \& not trustworthy, but a nice fellow overall. Good to \ get acquainted with. \& T} atehwa Panu T{ \& the same person \& T} root superuser T{ \& found in every Unix under the sky \& T} \& .TE \& .TS r c l . j " , L J ` _ ' \& .TE .PP .RS 4 .IP \(bu 4 \&still works? .RE stx2any/regression/prefix-strip.gather_stx_titles0000644000175000017500000000001610423671243024415 0ustar pkalliokpkalliok00000000000000-p regression stx2any/regression/table.latex0000644000175000017500000000141010423671243020430 0ustar pkalliokpkalliok00000000000000\documentclass[a4paper,notitlepage]{article} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{} \author{} \date{} \begin{document} \maketitle \tableofcontents \begin{tabular}{p{0.3\textwidth}c} Emigration is nice! & foo \\ Immigration is even nicer! & bar \\ \end{tabular} \begin{tabular}{llp{0.3\textwidth}} account & name & miscellaneous notes \\ \hline pkalliok & Panu & not trustworthy, but a nice fellow overall. Good to get acquainted with. \\ atehwa & Panu & the same person \\ root & superuser & found in every Unix under the sky \\ \end{tabular} \begin{tabular}{rcl} j&"&,\\ L& &J\\ `&_&'\\ \end{tabular} \begin{itemize} \item still works? \end{itemize} \end{document} stx2any/LICENSE0000644000175000017500000000115210423671243015132 0ustar pkalliokpkalliok00000000000000 ! stx2any - an implementation of conversion from Stx to multiple formats Authors:: - (c) 2003, 2004, 2005, 2006 Panu Kalliokoski This software is available free of charge for distribution, modification and use (by executing the program) as long as the following conditions are met: # Every work copied or derived from this software distributed in any form must come with this license; # The only permitted change to this license is adding one's name in the authors section when having modified the software. THE AUTHORS CANNOT BE HELD RESPONSIBLE FOR ANY DIRECT OR INDIRECT HARM THIS SOFTWARE MIGHT CAUSE. stx2any/latex/0000755000175000017500000000000010446213102015232 5ustar pkalliokpkalliok00000000000000stx2any/latex/make.lm40000644000175000017500000001052110424125205016566 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.latex)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) Definitions for LaTeX. LaTeX provides its own hack diversion, ''preamble''. There is also some neatism to its own name. {{{ w_define_div(preamble) define(`LaTeX', ``\LaTeX{}'') define(`@w_documentclass', `article') define(`w_documentclass', `w_set_or_get(`@w_documentclass', `$1')') }}} Some macros (URLs and inline graphics) need package declarations. We use this to only include them once. {{{ define(`w_ensure_pkg', `ifdef(`@w_has_pkg_$1',, `define(`@w_has_pkg_$1',t)w_begdiv(preamble)\usepackage{$1} w_enddiv(preamble)')') }}} Paragraphs and headings. We leave paragraphs to LaTeX itself. It has similar paragraph rules to ours. {{{ define(`w_paragraph',) define(`w_headl', `w_newindent(0)'dnl `\w_pickn($1, section, subsection, subsubsection, paragraph)`''dnl `ifelse(w_do_numbering,true,,*)'dnl `{ifelse(w_do_link_abbr,true,`w_autolabel(`$2')',`$2')}') }}} Block system environments. Finding definitions in lists is left to LaTeX. It has similar rules to ours. {{{ w_define_env(-, `\begin{itemize}w_nl`'', `\end{itemize}w_nl`'') w_define_env(#, `\begin{enumerate}w_nl`'', `\end{enumerate}w_nl`'') w_define_env(:, `\begin{description}w_nl`'', `\end{description}w_nl`'') w_define_env(q, `\begin{quotation}w_nl`'', `\end{quotation}w_nl`'') w_define_env(t,,) define(`w_listitem', `\item ') define(`w_defnterm', `\item[{$1}] ') }}} Other environments. {{{ w_define_env(`footnote', `\footnote{', `}') w_define_env(`litblock', `w_ensure_pkg(alltt)\begin{alltt}', `\end{alltt}') w_define_env(`center', `\begin{center}', `\end{center}') w_define_env(`abstract', `w_begdiv(ingr)\begin{abstract}`'w_nl', `\end{abstract}w_enddiv(ingr)`'w_nl') w_define_env(`comment', `pushdef(`w_softbr', `% ')pushdef(`w_softpara', `% ')% ', `w_nl`'popdef(`w_softbr')popdef(`w_softpara'){}') w_define_env(`w_float_n', `\begin{figure}[htb]', `\caption{$1}w_nl\end{figure}') w_define_env(`w_float_f', `\begin{figure}[tbp]', `\caption{$1}w_nl\end{figure}') w_define_env(`w_float_m', `\marginpar{', `\\ $1 }') }}} Emphasis. {{{ define(`w_literal', `\litfmt{$1}') define(`w_emph', `\emph{$1}') define(`w_strong', `\strongemph{$1}') }}} Other inlines. {{{ define(`w_linebr', `\\') define(`w_sectbreak', `w_nl\begin{center}\rule{0.5\textwidth}{0.0$1em}\end{center}w_nl') define(`w_link', `w_ensure_pkg(url)`'$2`'w_footnote(`\url{$1}')') define(`w_img', `w_ensure_pkg(graphicx)\includegraphics{w_file(`$1.'w_picture_suffix)}') define(`w_label', `\label{$1}$2') define(`w_refer', `$2 (\pageref{$1})') define(`w_url', `w_ensure_pkg(url)\url{$1}') }}} Slides. {{{ w_define_env(`slide', `w_ensure_slides\begin{slide}', `\end{slide}') define(`w_ensure_slides', `w_documentclass(seminar)'dnl `ifdef(`@w_slidestyle_done',, `define(`@w_slidestyle_done',t)undefine(`w_make_title')'dnl `define(`@w_doctype_parms', w_gather(patsubst(defn(`@w_doctype_parms'), a4paper, a4)))'dnl `ifelse(w_slideheader`'w_slidefooter,,,`w_slidestyle_setup')')') define(`w_slidestyle_setup', `w_begdiv(preamble)\newpagestyle{slidepage} {\hfill{}w_slideheader\hfill{}}{\hfill{}w_slidefooter\hfill{}} w_enddiv(preamble)w_begdiv(frontmatter)\slidepagestyle{slidepage} w_enddiv(frontmatter)') }}} Tables. {{{ define(`w_make_tablespec', `ifelse(`$*',,, `ifelse(`$1',p,`p{0.3\textwidth}',`$1')`'w_make_tablespec(shift($@))')') w_define_env(`w_table', `pushdef(`w_caption', `\caption{$1}')'dnl `\begin{tabular}{w_make_tablespec($@)}w_nl', `popdef(`w_caption')\end{tabular}w_nl') w_define_env(`w_row',,`undefine(`@w_in_row_flag')\\') w_define_env(`w_cell', `ifdef(`@w_in_row_flag',`&')define(`@w_in_row_flag',t)',) define(`w_table_rule', `\hline') }}} Special and quoted characters. {{{ define(`w_lt', `\ensuremath{<}') define(`w_gt', `\ensuremath{>}') define(`w_bs', `\ensuremath{\backslash}') define(`w_obr', `\{') define(`w_bar', `\ensuremath{|}') define(`w_cbr', `\}') define(`w_amp', `\&') define(`w_us', `\_') define(`w_ct', `\^{}') define(`w_td', `\~{}') define(`w_dol', `\$') define(`w_hs', `\#') define(`w_pct', `\%') define(`w_emdash', `---') define(`w_endash', `--') define(`w_ellipsis', `\ldots{}') define(`w_copyrightsign', `\copyright{}') define(`w_trademarksign', `\texttrademark{}') define(`w_larrow', `\ensuremath{\leftarrow{}}') define(`w_rarrow', `\ensuremath{\rightarrow{}}') }}} stx2any/latex/settings.lsh0000644000175000017500000000075710424125242017616 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ test -z "$NUMBERING" && NUMBERING=on test -z "$PAPERCONF" && PAPERCONF=/etc/papersize test -z "$PAPERSIZE" && test -f "$PAPERCONF" && \ PAPERSIZE=`sed '/^#/d' "$PAPERCONF"` test -z "$PAPERSIZE" && PAPERSIZE=a4 test -z "$LATEX_PARAMS" && LATEX_PARAMS="${PAPERSIZE}paper,notitlepage" M4OPTIONS="$M4OPTIONS -D@w_doctype_parms=$LATEX_PARAMS" test -z "$PIC_SUFFIX" && PIC_SUFFIX=eps }}} stx2any/latex/templ.lm40000644000175000017500000000136310424125211016773 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ \documentclass[defn(`@w_doctype_parms')]{defn(`@w_documentclass')} ifdef(`@w_language',`\usepackage[defn(`@w_language')]{babel}',`dnl') \usepackage[T1]{fontenc} ifelse(defn(`@w_char_coding'),ascii,`dnl',`\usepackage[defn(`@w_char_coding')]{inputenc}') \newcommand{\strongemph}[1]{\textbf{#1}} \newcommand{\litfmt}[1]{\texttt{#1}} \title{defn(`@w_title')} \author{defn(`@w_author')} \date{defn(`@w_date')} w_dumpdiv(preamble)dnl \begin{document} w_dumpdiv(frontmatter)dnl ifelse(w_make_title,true,\maketitle,`dnl') w_dumpdiv(ingr)dnl ifelse(w_make_toc,true,\tableofcontents,`dnl') w_dumpdiv(body)dnl w_dumpdiv(backmatter)dnl \end{document} }}} stx2any/README0000644000175000017500000000426510423671243015015 0ustar pkalliokpkalliok00000000000000w_title(Stx document tools distribution)dnl w_doc_id(stxreadme)dnl w_author(Panu A. Kalliokoski)dnl ! What is this? This software distribution is a bunch of tools to deal with structured text (Stx). Stx is a kind of plain text format with semantic markup. Stx is documented in: - [Stx-doc.html] - [Stx-ref.html] Of some interest may be also [stxaccred]. There are [a homepage][1] (currently in the author's wiki), and a distribution page at [2] for this project. You can contact the author at [mymail]. [1] http://sange.fi/~atehwa/cgi-bin/piki.cgi/stx2any [2] http://sange.fi/~atehwa/ [mymail] mailto:atehwa@sange.fi ! Included tools The following tools are included: [s2aman]:: This is the main tool, an utility to convert Stx into other formats. [ssman]:: A simple literal programming tool for document-programs written in Stx. [gstman]:: A utility for generating cross references between documents written in Stx. [eufsman]:: A utility for producing "Usage:" messages and manual pages from the same source. [h2sman]:: Conversion tool from HTML to Stx. This makes it easy to import documents written in other formats into Stx. Besides, you can tidy an HTML document by converting it first into Stx, then back into (X)HTML. ''stx-mode.el'':: An ''emacs'' mode for writing Stx documents. Provides syntax highlighting, paragraph filling, and simple interfaces to ''stx2any'' for those who cannot use the command line. ! Installation A traditional ''make && make install'' will do. You can override the ''make'' variable ''PREFIX'' to install somewhere else than ''/usr''. Other variables you might want to override include ''EMACSDIR'' and ''MANDIR''. Take a look at the Makefile[../Makefile]. The installation process of stx2any normally uses ''w3m'' to produce "usage" messages from Stx. If you don't want to install ''w3m'', you can give ''make'' the option ''BUILD_USAGE_WITH=plain'' to avoid using ''w3m''. The only consequence is that "usage" messages (the output of ''stx2any --help'', for instance) will look cruder. If you have a debian box, you can build a debian package directly by saying ''fakeroot debian/rules binary'' and installing the resulting package with ''dpkg -i''. stx2any/scripts/0000755000175000017500000000000010424125514015611 5ustar pkalliokpkalliok00000000000000stx2any/scripts/strip_stx0000755000175000017500000000153710424125505017604 0ustar pkalliokpkalliok00000000000000#!/bin/sh # This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski # and released under the license in ../LICENSE BASE=. usage() { cat $BASE/messages/strip_stx.usage 1>&2 exit $1 } NOT_PROG=d SEP=`echo | tr '\012' '\001'` BEG_COMMENT=d END_COMMENT=d BEG_STR= END_STR= while true; do case "$1" in -c) NOT_PROG="s$SEP^$SEP$2$SEP" shift ;; -B) BEG_COMMENT="s$SEP$SEP$2$SEP" END_COMMENT="s$SEP$SEP$3$SEP" BEG_STR="$2" END_STR="$3" test "$NOT_PROG" = d && NOT_PROG=b shift shift ;; --help|-\?) usage 0 ;; --version|-V) cat $BASE/messages/version.msg exit 0 ;; *) break esac shift done ERRORS= test -n "$BEG_STR" && echo "$BEG_STR" sed -e "/^{{{$/,/^}}}$/! $NOT_PROG" \ -e "/^}}}\$/$BEG_COMMENT" \ -e "/^{{{\$/$END_COMMENT" $@ || ERRORS=yes test -n "$END_STR" && echo "$END_STR" test -z "$ERRORS" || usage 1 stx2any/scripts/html2stx0000755000175000017500000002053210424125472017331 0ustar pkalliokpkalliok00000000000000#!/usr/bin/env python # This file is copyright (c) 2004 Aaron Swartz, copyright (c) 2004, 2005, 2006 Panu Kalliokoski # This file is released under the GNU General Public License (GPL), version 2. # Derived from html2text, version 2.11, by Aaron Swartz. """html2stx: Turn HTML into neat Stx source, stripping everything that cannot be expressed in Stx.""" __author__ = "Panu A. Kalliokoski" __copyright__ = "(C) 2004 Aaron Swartz; 2004, 2005 Panu Kalliokoski. GNU GPL 2." import re, sys, urllib, htmlentitydefs, codecs, StringIO import sgmllib sgmllib.charref = re.compile('&#([xX]?[0-9a-fA-F]+)[^0-9a-fA-F]') # Use Unicode characters instead of their ascii psuedo-replacements UNICODE_SNOB = 0 ### Entity Nonsense ### def name2cp(k): if k == 'apos': return ord("'") if hasattr(htmlentitydefs, "name2codepoint"): # requires Python 2.3 return htmlentitydefs.name2codepoint[k] else: k = htmlentitydefs.entitydefs[k] if k.startswith("&#") and k.endswith(";"): return int(k[2:-1]) # not in latin-1 return ord(codecs.latin_1_decode(k)[0]) unifiable = {'rsquo':"'", 'lsquo':"'", 'rdquo':'"', 'ldquo':'"', 'mdash':' -- ', 'ndash':'--'} unifiable_n = {} for k in unifiable.keys(): unifiable_n[name2cp(k)] = unifiable[k] def charref(name): if name[0] in ['x','X']: c = int(name[1:], 16) else: c = int(name) if not UNICODE_SNOB and c in unifiable_n.keys(): return unifiable_n[c] else: return unichr(c) def entityref(c): if not UNICODE_SNOB and c in unifiable.keys(): return unifiable[c] else: try: name2cp(c) except KeyError: return "&%s;" % c else: return unichr(name2cp(c)) def replaceEntities(s): s = s.group(1) if s[0] == "#": return charref(s[1:]) else: return entityref(s) r_unescape = re.compile(r"&(#?[xX]?(?:[0-9a-fA-F]+|\w{1,8}));") def unescape(s): return r_unescape.sub(replaceEntities, s) def fixattrs(attrs): # Fix bug in sgmllib.py if not attrs: return [] newattrs = [] for attr in attrs: newattrs.append((attr[0], unescape(attr[1]))) return newattrs ### End Entity Nonsense ### def hn(tag): if not (tag[0] == 'h' and len(tag) == 2): return False try: return max(int(tag[1])-1, 1) except ValueError: return False class _html2text(sgmllib.SGMLParser): line_length = 72 begspace_re = re.compile('^( *)(.*)$') endspace_re = re.compile('^(.*)( +)$') def __init__(self, out=sys.stdout.write): sgmllib.SGMLParser.__init__(self) if out is None: self.out = self.outtextf else: self.out = out self.outtext = u'' self.quiet = [] self.p_p = 0 self.outcount = 0 self.list = [] self.space = '' self.start = 1 self.blockquote = 0 self.pre = 0 self.lastWasNL = 1 self.column = 0 self.charset = 'latin1' def outtextf(self, s): self.outtext += s def close(self): sgmllib.SGMLParser.close(self) self.pbr() self.o('', 0, 'end') return self.outtext def handle_charref(self, c): self.o(charref(c)) def handle_entityref(self, c): self.o(entityref(c)) def unknown_starttag(self, tag, attrs): self.handle_tag(tag, attrs, 1) def unknown_endtag(self, tag): self.handle_tag(tag, None, 0) def handle_tag(self, tag, attrs, start): attrs = dict(fixattrs(attrs)) if not start: self.space = '' if hn(tag): self.p() if start: self.pre = 1 self.o(hn(tag)*"!" + ' ') else: self.pre = 0 if tag in ['p', 'div']: self.p() if tag == "br" and start: self.o("//") self.pbr() if tag == 'hr' and start: self.p() self.o('----') self.p() if tag in ["head", "style", "script"]: if start: self.quiet.append(1) else: self.quiet.pop() if tag == 'title': if start: self.quiet.append(0) self.o("w_title(") else: self.o(")dnl") self.begin_line() self.quiet.pop() if tag == 'meta' and start: name = attrs.get('name') or \ attrs.get('http-equiv') or '' content = attrs.get('content') if name.lower() == 'author': self.o("w_author(%s)dnl" % content, 0, 1) self.begin_line() elif name.lower() in ['date', 'last-modified']: self.o("w_date(%s)dnl" % content, 0, 1) self.begin_line() elif name.lower() == 'content-type': match = re.search('[Cc]harset=(.*)', content) if match: try: charset = { 'ISO-8859-1':'latin1', 'ISO-8859-15':'latin9', 'US-ASCII':'ascii', 'UTF-8':'utf8' }[match.group(1).upper()] except KeyError: charset = 'latin1' self.charset = charset self.o("w_char_coding(%s)dnl" % charset, 0, 1 ) self.begin_line() if tag == "dl": self.p() if tag == "dt": if start: self.pre = 1 self.pbr() else: self.o("::") self.pre = 0 self.pbr() if tag in ["blockquote", "dd"]: if start: if tag != "dd": self.p() self.blockquote += 1 else: self.blockquote -= 1 if tag == "dd": self.pbr() else: self.p() if tag in ['em', 'i', 'u']: self.o("_") if tag in ['var', 'cite', 'dfn']: self.o("/") if tag in ['kbd', 'samp', 'code', 'tt']: self.o("''") if tag == "q": self.o('"') if tag in ['strong', 'b']: self.o("*") if tag == "a": if start: tgt = attrs.get('href', '') lbl = attrs.get('name', '') if lbl: self.o("w_label(%s, " % lbl) elif tgt and tgt[0]=='#': self.o("w_refer(%s, " % tgt[1:]) else: self.o("w_link(%s, " % tgt) else: self.o(")") if tag == "img" and start: tgt = re.sub('\.(jpe?g|gif|png)$', '', attrs.get('src', '')) alt = attrs.get('alt', '') self.o("w_img(%s, %s)" % (tgt, alt)) if tag in ["ol", "ul"]: if start: self.list.append(tag) else: self.list.pop() self.p() if tag == 'li': if start: self.pbr() if self.list: li = self.list.pop() else: li = "ul" if li == "ul" and len(self.list)<=1: self.o("- ") elif li == "ul": self.o("* ") elif li == "ol": self.o("# ") self.list.append(li) else: self.pbr() if tag == 'table': if start: self.p() self.o('w_beg(table)') self.pbr() else: self.pbr() self.o('w_end(table)') self.p() if tag == 'tr' and not start: self.o("//") self.begin_line() if tag in ['td', 'th'] and not start: self.o("||") if tag == "pre": if start: self.p() self.pre = 1 self.o("{{{") else: if not self.lastWasNL: self.pbr() self.o("}}}") self.pre = 0 self.p() self.start = start def pbr(self): if self.p_p == 0: self.p_p = 1 def p(self): self.p_p = 2 def begin_line(self): self.out('\n') self.out('\t' * self.blockquote) self.out(' ' * len(self.list)) self.column = self.blockquote * 8 + len(self.list) * 2 self.lastWasNL = 1 def o(self, data, puredata=0, force=0): if self.quiet and self.quiet[-1] and not force: return if puredata and not self.pre: data = re.sub('\n[ \t]*', '\n', data) data = re.sub('\\s', ' ', data) sp, data = self.begspace_re.match(data).groups() self.space += sp if not data and not force: return space = self.space if force == 'end': # It's the end. self.p_p = 0 self.out("\n") space = '' if self.p_p: if self.p_p > 1 and not self.lastWasNL: self.out('\n') self.begin_line() space = '' if space and not self.start and not self.lastWasNL: if self.column > self.line_length: self.begin_line() else: self.out(space) if not self.pre: while len(data) + self.column > self.line_length: spl = self.split_line( data ) if not spl: break line, data = spl self.out(self.decode(line)) self.begin_line() self.p_p = 0 if puredata and not self.pre: match = self.endspace_re.match(data) if match: data, self.space = match.groups() else: self.space = '' else: self.space = '' self.out(self.decode(data)) self.column += len(data) if data: self.lastWasNL = data[-1] == '\n' self.outcount += 1 def split_line( self, line ): match = re.match('^(.{0,%d}) (.*)$' % max(self.line_length - self.column, 15), line) if not match: return None return match.groups() def decode(self, s): if type(s) is unicode: if self.charset == 'latin9': return s.encode('latin1') return s.encode(self.charset) return s def handle_data(self, data): self.o(data, 1) self.start = 0 def unknown_decl(self, data): pass def html2text_file(html, out=sys.stdout.write): h = _html2text(out) h.feed(html) h.feed("") return h.close() if __name__ == "__main__": try: data = open(sys.argv[1], 'r').read() except IndexError: data = sys.stdin.read() html2text_file(data) stx2any/scripts/gather_stx_titles0000755000175000017500000000244010424125332021271 0ustar pkalliokpkalliok00000000000000#!/bin/sh # This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski # and released under the license in ../LICENSE BASE=. usage() { cat $BASE/messages/gather_stx_titles.usage 1>&2 exit $1 } while test -n "$1"; do case "$1" in -f) FROM_SUFFIX="$2" shift ;; -f*) FROM_SUFFIX=`echo $1 | cut -c3-` ;; -t) TO_SUFFIX="$2" shift ;; -t*) TO_SUFFIX=`echo $1 | cut -c3-` ;; -p) PREFIX="$2" shift ;; -p*) PREFIX=`echo $1 | cut -c3-` ;; --help|-\?) usage 0 ;; --version|-V) cat $BASE/messages/version.msg exit 0 ;; *) break esac shift done for i in $@; do echo -n "define(\`@w_file_exists_" echo -n "$i" | sed -e "s#$FROM_SUFFIX\$#$TO_SUFFIX#" -e "s#^$PREFIX/*##" | tr -d '\012\015' echo "', t)dnl" done ( cat << DEF divert(-1) define(\`w_quotewrap', \`\`\`\$1''') define(\`w_makesubst', \`patsubst(patsubst(\`\$1', \`$FROM_SUFFIX\$', \`$TO_SUFFIX'), \`^$PREFIX/*',)') define(\`w_file', \`w_quotewrap(w_makesubst(w_real_file))') define(\`w_title', \`ifelse(\`\$1',,,\`divert(0)dnl') \`define'(\`\`@w_title_of_''w_file, \`\`\$1'')\`dnl' divert(-1)') define(\`w_doc_id', \`divert(0)dnl \`define'(\`\`@w_filename_of_\$1'', w_file)\`dnl' divert(-1)') DEF for i in $@; do echo "define(\`w_real_file', \`$i')" sed -f $BASE/common/header.sed $i done ) | m4 || usage 1 stx2any/scripts/stx2any0000755000175000017500000000720510424125512017151 0ustar pkalliokpkalliok00000000000000#!/bin/sh # This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski # and released under the license in ../LICENSE BASE=. usage() { cat $BASE/messages/stx2any.usage 1>&2 exit $1 } DEVICE=html TEMPLDEVICE= SECURE= QUOTE_AFTER= NUMBERING= TABLE_OF_CONTENTS= MAKE_TITLE=on LINKABBREVS= EMDASH_SEP=" " LATEX_PARAMS= HTML_PARAMS= PIC_SUFFIX= PREPROC="" POSTPROC=cat M4OPTIONS="-I$BASE/site-packages" SOURCES= while test -n "$1"; do case "$1" in -T) DEVICE="$2" shift ;; -T*) DEVICE=`echo $1 | cut -c3-` ;; --quote) QUOTE_AFTER="-f $BASE/common/quote.sed" ;; --quote-me-harder) PREPROC="$PREPROC -f $BASE/common/quote_us.sed" ;; --more-secure) SECURE="$BASE/common/secure.m4" ;; --numbering) NUMBERING="$2" shift ;; --table-of-contents) TABLE_OF_CONTENTS="$2" shift ;; --make-title) MAKE_TITLE="$2" shift ;; --link-abbrevs) PREPROC="$PREPROC -f $BASE/common/linking.sed" M4OPTIONS="$M4OPTIONS -Dw_do_link_abbr=true" LINKABBREVS=on ;; --no-template) TEMPLDEVICE=common ;; --symmetric-crossrefs) M4OPTIONS="$M4OPTIONS -Dw_symmetric_crossrefs=t" ;; --latex-params) LATEX_PARAMS="$2" shift ;; --html-params) HTML_PARAMS="$2" shift ;; --picture-suffix) PIC_SUFFIX="$2" shift ;; --no-emdash-separate) EMDASH_SEP= ;; --sed-preprocessor) PREPROC=" -f \"$2\" $PREPROC" shift ;; --help|-\?) usage 0 ;; --version|-V) cat $BASE/messages/version.msg exit 0 ;; -) SOURCES="$SOURCES -" ;; -*) M4OPTIONS="$M4OPTIONS \"$1\"" ;; *) SOURCES="$SOURCES $1" esac shift done if test -n "$SECURE"; then if echo "$M4OPTIONS" | grep '[;|\\`&>]' >/dev/null; then echo "Unsecure characters in the options: $M4OPTIONS" exit 1 fi if echo "$PREPROC" | grep '[;|\\`&>]' >/dev/null; then echo "Unsecure characters in the preprocessor script: $M4OPTIONS" exit 1 fi fi case "$DEVICE" in ps) POSTPROC='groff -Tps -t -man' DEVICE=man ;; text) POSTPROC='w3m -dump -T text/html -cols 80' DEVICE=html ;; xhtml) POSTPROC='tidy -q -asxml' DEVICE=html ;; esac if test ! -d "$BASE/$DEVICE"; then echo "unknown output format: $DEVICE" 1>&2 exit 1 fi . $BASE/$DEVICE/settings.sh test -z "$TEMPLDEVICE" && TEMPLDEVICE="$DEVICE" test -z "$TABLE_OF_CONTENTS" && TABLE_OF_CONTENTS="$NUMBERING" set_onoff_option() { case "$1" in y*|on) M4OPTIONS="$M4OPTIONS -D$2=true" ;; n*|off) ;; *) echo "Unknown $3 setting: $1" 1>&2 exit 1 esac } set_onoff_option "$NUMBERING" w_do_numbering numbering set_onoff_option "$TABLE_OF_CONTENTS" w_make_toc table-of-contents set_onoff_option "$MAKE_TITLE" w_make_title make-title test -z "$SOURCES" && SOURCES=- trap 'echo "Subprocess m4 exited with an error" 1>&2 && echo "Try \"$0 --help\" for help on command line options" 1>&2' 13 PARENT=$$; export PARENT for i in $SOURCES; do echo -n "define(\`w_real_file', \`$i')" echo "define(\`w_line_base', not yet in file)dnl" test -n "$LINKABBREVS" -a "X$i" != "X-" && \ sed -f $BASE/common/gatherlinkmap.sed "$i" echo "define(\`w_line_base', __line__)dnl" cat "$i" done | \ sed -f $BASE/common/quote_quotes.sed | \ eval sed -f $BASE/common/header.sed -f $BASE/common/wrapcalls.sed $PREPROC | \ sed -f $BASE/common/emphasis.sed | \ sed -f $BASE/common/inline.sed -f $BASE/common/block.sed $QUOTE_AFTER | \ ( eval m4 "\"-Dw_outputfmt=$DEVICE\"" "\"-Dw_picture_suffix=$PIC_SUFFIX\"" \ "\"-Dw_emdash_separate=$EMDASH_SEP\"" "\"-D@w_bodytag_params=$HTML_PARAMS\"" \ "$M4OPTIONS" $SECURE \ $BASE/common/common.m4 \ $BASE/common/markup.m4 \ $BASE/$DEVICE/make.m4 \ $BASE/common/begin.m4 - $BASE/common/end.m4 \ $BASE/$TEMPLDEVICE/templ.m4 \ $BASE/common/cleanup.m4 || kill -13 $PARENT ) | \ $POSTPROC stx2any/scripts/extract_usage_from_stx0000755000175000017500000000114310424125325022315 0ustar pkalliokpkalliok00000000000000#!/bin/sh # This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski # and released under the license in ../LICENSE BASE=. usage() { cat $BASE/messages/extract_usage_from_stx.usage 1>&2 exit $1 } case "$1" in --help|-\?) usage 0 ;; --version|-V) cat $BASE/messages/version.msg exit 0 ;; esac sed -n \ -e '/^! *SYNOPSIS/,/^!/{' \ -e '/^$/,/./{' \ -e 's#^[^ !]#Usage: &#' \ -e '}' \ -e '/^!/!p' \ -e '}' \ -e '/^! *OPTIONS/,/^!/{' \ -e 's#^! *OPTIONS.*#Options:#p' \ -e '/^!/d' \ -e '/^[^ ].*::$/,/\./{' \ -e 's#\. .*#.#' \ -e 'p' \ -e '}' \ -e '}' $@ || usage 1 stx2any/common/0000755000175000017500000000000010471044066015416 5ustar pkalliokpkalliok00000000000000stx2any/common/quote.lsed0000644000175000017500000000071010424125234017415 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Quoting of possible special characters. {{{ s#<#`'w_lt`'#g s#>#`'w_gt`'#g s#&#`'w_amp`'#g s#^\.#w_bldot`'# s#^'#w_blap`'# s#\\#`'w_bs`'#g s#{#`'w_obr`'#g s#|#`'w_bar`'#g s#}#`'w_cbr`'#g s#\^#`'w_ct`'#g s#~#`'w_td`'#g s/\([^,]\)#/\1`'w_hs`'/g s#%#`'w_pct`'#g }}} The special case of ''w_hs'' is because numbered lists put it in the call of w_item. stx2any/common/wrapcalls.lsed0000644000175000017500000000066110424125237020260 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Prepare input so that every direct macro call can be checked against definedness. We protect against meddling with defines, because sometimes the users will want to legitimately redefine stx2any macros. {{{ /define/!{ /`/!{ s#\([^A-Za-z0-9]\)\(w_[a-z_][a-z_]*\)#\1w_invoke(`\2')#g s#^w_[a-z_][a-z_]*#w_invoke(`&')# } } }}} stx2any/common/quote_us.lsed0000644000175000017500000000113010424125236020123 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Quoting underscores and dollar signs... First, quote-quote underscores that should _not_ be quoted. {{{ s#__line#UNDERSCORETHINGYUNDERSCORETHINGYline#g s#__file#UNDERSCORETHINGYUNDERSCORETHINGYfile#g s#w_#wUNDERSCORETHINGY#g t moreus : moreus s#\(UNDERSCORETHINGY[a-z]*\)_#\1UNDERSCORETHINGY#g t moreus }}} Then, do the actual quoting and quote-quote unquoting. {{{ s#_#`'w_us`'#g s#UNDERSCORETHINGY#_#g }}} Dollar signs are also problematic. {{{ /define/!{ /`/!{ s#\$#`'w_dol`'#g } } }}} stx2any/common/inline.lsed0000644000175000017500000000266510424125230017545 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.inl)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Inline elements may happen anywhere in text. However, they are different from emphasis in that they are not constrained by paragraph boundaries and / or don't require both an opening and closing mark to be present. Footnotes are transformed directly into the corresponding environment: {{{ s#\[\[$#`'w_beg(footnote)#g s#^\( *\)\]\]#\1w_end(footnote)`'#g s#\[\[[- ]#`'w_beg(footnote)`'#g s#[- ]\]\]#`'w_end(footnote)`'#g }}} Several formatting rules do not apply within a literal block. Because of this, we branch past the rest of this stuff _and_ all blocks: {{{ /^{{{$/,/^}}}$/ { s#^}}}$#w_end(litblock)# s#^{{{$#w_beg(litblock)# b end } }}} Special characters. {{{ s#^\( *\)-- #\1w_emdash`'w_emdash_separate`'# s# -- #`'w_emdash_separate`'w_emdash`'w_emdash_separate`'#g s# --$#`'w_emdash_separate`'w_emdash# s#\([A-Za-z0-9])*\)--\((*[A-Za-z0-9]\)#\1`'w_endash`'\2#g s#\.\.\.\([] ,.;:?!)}>"-]\)#`'w_ellipsis\1#g s#\.\.\.$#`'w_ellipsis# s#\([ ([{<"-]\)([cC])\([ :1-9]\)#\1w_copyrightsign\2#g s#^([cC])\([ :1-9]\)#w_copyrightsign\1#g s#\([ ([{<"-]\)([cC])$#\1w_copyrightsign# s#([tT][mM])#`'w_trademarksign`'#g s# -> # w_rarrow #g s#^-> #w_rarrow # s# ->$# w_rarrow# s# <- # w_larrow #g s#^<- #w_larrow # s# <-$# w_larrow# }}} Some constructs that may occur most anywhere: {{{ s#||#`'w_horizbr`'#g s#//$#`'w_linebr# }}} stx2any/common/end.lm40000644000175000017500000000111310424125113016565 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE End a document. Try to make sure everything is closed. (This is not perfect; for example the sectioning system of docbook-xml is not invoked. Docbook-xml sections don't play nicely with diversions anyway.) {{{ w_newindent(0)`'w_setblocktype(n)`'w_softpara`'dnl }}} Close the default environment begun in begin.m4 and check everything went as should. Then, prepare for the actual output (the template). {{{ w_end(n)`'w_check_env`'w_enddiv(body)`'w_check_div`'divert(0)dnl }}} stx2any/common/markup.lm40000644000175000017500000004131510471044066017337 0ustar pkalliokpkalliok00000000000000w_title(stx2any -- low-level and common markup facilities)dnl w_doc_id(s2aimpl.markup)dnl w_author(Panu A. Kalliokoski)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) Included herein are macros that transform "low-level" annotations made in the ''sed'' phase into "high-level" macro calls to be defined specific to output format. Actually, this border is very fuzzy: some output formats don't need these helpers (e.g. LaTeX doesn't need footnote facilities), and may redefine some markup on a lower level. Because overriding definitions made here is easy, this file is also used for providing some sensible (output format independent) defaults for several macros. But the first thing to do is to disable the ''m4'' comment mechanism. It is the single most common source of syntax mistakes in ''m4'' files. Because traditional ''m4'' won't let us disable it entirely, let's make it something you're relatively unlikely to run into. {{{ changecom(`#%$bo',`ob$#%') }}} ! Defaults The default character set. {{{ w_char_coding(latin1) }}} Defaults for some simple macros. {{{ define(`w_horizbr', `||') define(`w_apo', ') define(`w_eline',) define(`w_section',) define(`w_url', `w_literal(`$1')') define(`w_man_desc', `ifelse(`$2',, `w_begdiv(ingr)w_emph(`$1')`'w_linebr`'w_nl`'w_enddiv(ingr)dnl', `$1 w_emdash $2 w_linebr')') define(`w_techemph', `w_emph(`$1')') define(`w_quotation', ``'w_bq`'w_bq`'$1`'w_apo`'w_apo`'') define(`w_emdash', `--') define(`w_endash', `--') define(`w_ellipsis', `...') define(`w_copyrightsign', `(c)') define(`w_sectbreak', `w_paragraph`'w_emdash w_emdash w_emdash`''dnl `ifelse(eval(`$1>4'),1,` w_emdash w_emdash`'')w_softopen') }}} Both itemised list types should have the same effect. In most situations, list items have the same effect, too. {{{ w_derive_env(*, -, 0,,,,) w_derive_env(*i, i, 0,,,,) w_derive_env(-i, i, 0,,,,) w_derive_env(#i, i, 0,,,,) }}} These environments have sensible defaults, but are overridden in some output formats when more appropriate markup is available. {{{ w_define_env(`compactlist', `pushdef(`w_eline', `w_linebr')', `popdef(`w_eline')') w_derive_env(`citation', q, 0,,,`w_linebr`'w_nl w_emdash $*`'w_nl',) w_derive_env(`abstract', q, 0,`w_begdiv(ingr)',,,`w_enddiv(ingr)') w_derive_env(`admonition', q, 1,`$1:w_nl`'',,,) define(`w_slideheader', `w_set_or_get(`@w_slideheader', `$*')') define(`w_slidefooter', `w_set_or_get(`@w_slidefooter', `$*')') w_define_env(`slide', `w_paragraph`'w_slideheader`'w_nl`'w_sbreak(3)`'w_softopen`'w_nl`'', `w_sbreak(3) w_paragraph`'w_slidefooter`'w_nl`'w_sbreak(5)`'w_softopen`'w_nl`'') }}} Quoted characters. We suppose most of these characters don't have any special meaning and let output format specific definitions override those that do. {{{ define(`w_lt', `<') define(`w_gt', `>') define(`w_amp', `&') define(`w_bldot', `.') define(`w_blap', ') define(`w_bs', `\') define(`w_obr', `{') define(`w_bar', `|') define(`w_cbr', `}') define(`w_us', `_') define(`w_ct', `^') define(`w_td', `~') define(`w_dol', `$') define(`w_hs', `#') define(`w_pct', `%') }}} ! Sectioning These macros just do section numbering for output formats that do not support it natively. They transform the low-level `w_headl' to the high-level `w_headline'. {{{ w_newcounter(subsubsection) w_newcounter(subsection, subsubsection) w_newcounter(section, subsection) w_newcounter(chapter, section) define(`w_headl', `w_newindent(0)'dnl `w_stepcounter(w_pickn(`$1', chapter, section, subsection, subsubsection))'dnl `w_headline(`$1', `w_maybe_tocline(w_number_of(`$1'), `$2')')') define(`w_maybe_tocline', `ifelse(w_make_toc, true, `w_index(toc, `$1', `$2')', w_do_link_abbr, true, `$1`'w_autolabel(`$2')', `$1`'$2')') define(`w_number_of', `ifelse(w_do_numbering, true, `w_sectionmark(`$1', chapter, section, subsection, subsubsection) ')') define(`w_sectionmark', `w_counter_arabic(`$2')`'ifelse(`$1',1,, `.w_sectionmark(decr(`$1'),shift(shift($@)))')') }}} ! Diversions Diversions common for every output format are declared here. {{{ w_define_div(`frontmatter') w_define_div(`ingr') w_define_div(`body') w_define_div(`backmatter') ifelse(w_make_toc,true,`w_define_div(`toc')',`w_define_trashcan(`toc')') }}} ''defs'' is a genuine trashcan diversion. The others serve as defaults for diversions that are not used for most output formats. {{{ w_define_trashcan(`defs') w_define_trashcan(`metas') w_define_trashcan(`preamble') }}} ! Footnotes By default, we gather footnotes in a diversion that can be dumped upon request. `w_footnote' is meant for end users; the environment is the real thing, used directly by abbreviations. {{{ w_define_div(`footnote') define(`w_footnote', ``'w_beg(footnote)`'$1`'w_end(footnote)`'') w_newcounter(footnote) w_define_env(footnote, `define(`@w_footnote_flag',t)'dnl `w_stepcounter(footnote)w_footnotemark(w_counter_arabic(footnote))`''dnl `w_begdiv(footnote)w_footnotemark(w_counter_arabic(footnote)) ', `w_linebr`'w_nl`'w_enddiv(footnote)') define(`w_dump_footnotes', `ifelse(defn(`@w_footnote_flag'),,,`$1`'w_dumpdiv(footnote)$2')'dnl `undefine(`@w_footnote_flag')') }}} ! Link abbreviation support The link abbreviations use two macros of their own, `w_generic_link' and `w_autolabel'. The label part is easy, though we have to provide infrastructure for making labels: {{{ w_newcounter(autolabel) define(`w_genlabel', `ifdef(`@w_label_used_$1', `w_stepcounter(autolabel)w_genlabel(`$1'w_counter_arabic(autolabel))', `define(`@w_label_used_$1',t)`$1'')') define(`w_tidystring', `patsubst(``$1'',`[^0-9A-Za-z`']',`.')') define(`w_make_autolabel', `define(`@w_label_of_$1',w_genlabel(w_tidystring(`$1')))') define(`w_autolabel', `ifdef(`@w_label_of_$1',,`w_make_autolabel(`$1')')'dnl `w_label(defn(`@w_label_of_$1'), `$1')') define(`w_autorefer', `w_refer(ifdef(`@w_label_of_$1',`defn(`@w_label_of_$1')',`w_tidystring(`$1')'), ifelse(`$2',,``$1'',``$2''))') }}} Now, generic links are quite a beast. They can become: # cross references (if the label exists), # cross links (if the document is known), # inline images or ordinary links (if it seems like we have a URL), # footnotes (if everything else fails) in this order of preference. They can link directly or indirectly (via a link data block). {{{ define(`w_generic_link', `ifdef(`@w_linkdata_of_$1', `w_generic_link(defn(`@w_linkdata_of_$1'),`$2')', `ifdef(`@w_label_of_$1', `w_autorefer(`$1', `$2')', `ifdef(`@w_filename_of_$1', `w_crosslink(`$1', `$2')', `ifdef(`@w_file_exists_$1', `w_crosslink(`$1', `$2')', `ifelse(index(`$1',img:),0, `w_img(substr(`$1', 4), `$2')', `ifelse(w_is_url(`$1'),t,`ifelse(`$2',,`w_url(`$1')',`w_link(`$1',`$2')')', `$2`'w_footnote(`$1')')')')')')')') define(`w_is_url', `ifelse(index(`$1',http://),0,t,index(`$1',https://),0,t,index(`$1',ftp://),0,t, index(`$1',gopher://),0,t,index(`$1',file:/),0,t,index(`$1',nntp://),0,t, index(`$1',mailto:),0,t,index(`$1',news:),0,t, index(`$1',./),0,t,index(`$1',../),0,t)') }}} ! End-user markup These definitions don't have anything to do with anything else and are included here because they are output format independent. They are expected to be invoked by the author of the document directly. These didn't fit anywhere else. {{{ define(`w_def_in_fmt', `ifelse(defn(`w_outputfmt'), `$1', `define(`$2', `$3')')') define(`w_invoke', `ifdef(`$1',`$1',`w_warning(`Unknown macro "$1" called')w_void')') define(`w_use', `ifdef(`@w_included_$1',, `define(`@w_included_$1',t)include(`$1.m4')`'')') }}} !! Indexes and cross-links Indexing something currently simply puts the same text both in the index diversion and in the current text, cross-referencing them. Some indexes should probably be lexicographically ordered, but this needs more careful designing. As it stands, this system is quite sufficient for lists of pictures and the like. {{{ define(`w_index', `ifelse(`$3',,`w_index(`$1',,`$2')', `w_make_autolabel(`$3')`$2'w_autolabel(`$3')`''dnl `w_begdiv(`$1')`$2'w_autorefer(`$3')`'w_linebr`'w_nl`'w_enddiv(`$1')')') define(`w_indexword', `define(`$2', `w_index(`$1', ``$2'')')') }}} Cross links are links between documents. To make a cross link properly to another document, a document needs to know something about the other document. w_crosslink(gstman) and `w_crosslink' together provide a way to keep track of this information. There are seven cases: # document contains both title and id, referenced by id # document contains both title and id, referenced by filename # document contains only title, referenced by filename # document contains only id, referenced by id # document contains only id, referenced by filename # document contains neither title nor id, referenced by filename # document unknown or doesn't exist Cases 1--3 produce a link to the file with text of title. Cases 4--6 produce a link with text of the filename, case 7 just whatever the document happened to be referenced by and a warning. A second argument, if present, will override the visible text produced by this macro. {{{ define(`w_file', `ifelse(w_is_url(`$1'),t,,ifdef(`w_base',defn(`w_base')/))`$1'') define(`w_crosslink', `ifdef(`@w_filename_of_$1', `w_crosslink(defn(`@w_filename_of_$1'),`$2')', `ifdef(`@w_file_exists_$1', `w_link(w_file(`$1'), ifelse(`$2',,`ifdef(`@w_title_of_$1', `defn(`@w_title_of_$1')',``$1'')',``$2''))', `w_warning(`Unknown cross link to "$1"')ifelse( `$2',,`$1',`$2')')')') }}} !! Some environments {{{ w_define_env(`text',,) w_define_env(`ifeq', `ifelse(`$1', `$2',, `w_begdiv(defs)')', `ifelse(`$1', `$2',, `w_enddiv(defs)')') }}} Floats and their infrastructure. {{{ w_define_env(`float', `w_beg(w_some_float_env(`$1'), shift($@))', `w_end(w_some_float_env(`$1'), shift($@))') define(`w_some_float_env', `ifelse(`$1',,`w_float_default', `w_ifdef_env(`w_float_'substr(`$1',0,1), ``w_float_'substr(`$1',0,1)', `w_some_float_env(substr(`$1',1))')')') w_define_env(`w_float_h', `w_sbreak(5)`'w_nl', `w_paragraph`'ifelse(`$1',,,w_caption(`$1')`'w_nl`')w_sbreak(5)`'w_nl') w_derive_env(`w_float_n', `w_float_h', 0, `define(`@w_footnote_flag',t)w_begdiv(footnote)',,, `w_enddiv(footnote)undefine(`@w_para_flag')') w_derive_env(`w_float_default', `w_float_n', 0,,,,) define(`w_caption', `$1') }}} ! Table infrastructure Common helpers used by both table environments. {{{ define(`w_begin_row', `w_reinit_list(columns)w_stepcounter(row)'dnl `w_beg(w_row, n, w_counter_arabic(row))`'') define(`w_begin_cell', `w_stepcounter(column)w_beg(w_cell, n, w_next_in_list(columns))') }}} Generic table environment. These transform low-level `w_horizbr' and `w_linebr' into high-level environment calls. The environment is based on `w_table', to be defined output-format-specifically. {{{ w_derive_env(`table', `w_table', 0, `w_setup_list(columns, $@)w_newcounter(column)w_newcounter(row,column)'dnl `pushdef(`w_pending_block_hook', `w_begin_row`'w_begin_cell`'')'dnl `pushdef(`w_linebr', `w_end(w_cell)`'w_end(w_row)`'define(`w_pending_block_hook', `w_begin_row`'w_begin_cell`'')')'dnl `pushdef(`w_horizbr', `w_end(w_cell)`'w_begin_cell`'')'dnl `pushdef(`w_sectbreak', `w_table_rule(w_length_list(columns))')', `undefine(`@w_para_flag')', , `popdef(`w_linebr')popdef(`w_horizbr')popdef(`w_sectbreak')'dnl `popdef(`w_pending_block_hook')w_delcounter(column)w_delcounter(row)'dnl `w_unsetup_list(columns)') }}} List tables. {{{ w_derive_env(`listtable', `w_table', 0, `w_setup_list(columns, $@)w_newcounter(column)w_newcounter(row,column)'dnl `pushdef(`w_sectbreak', `w_table_rule(w_length_list(columns))')'dnl `w_push_env(*)w_derive_env(*,w_listtable_level,0,,,,)'dnl `w_newcounter(w_listtable)w_push_env(*i)undefine(`@w_para_flag')',,, `w_pop_env(*i)w_pop_env(*)w_delcounter(w_listtable)popdef(`w_sectbreak')'dnl `w_unsetup_list(columns)w_delcounter(column)w_delcounter(row)') w_define_env(`w_listtable_level', `w_stepcounter(w_listtable)'dnl `ifelse(w_counter_arabic(w_listtable),1,`w_derive_env(*i,w_row,0,,,,)', w_counter_arabic(w_listtable),2,`w_derive_env(*i,w_cell,0,,,,)', `w_error(`Hm, trying to make three-dimensional tables?')')', `w_stepcounter(w_listtable,-1)'dnl `ifelse(w_counter_arabic(w_listtable),1,`w_derive_env(*i,w_row,0,,,,)', w_counter_arabic(w_listtable),0,`w_define_env(*i,,)')') }}} ! Paragraphs These transform low-level `w_para' calls into high-level `w_paragraph' calls. {{{ define(`w_softopen', `define(`@w_para_flag',t)') define(`w_para', `w_softopen`'w_softpara') define(`w_beg_para', `ifelse(defn(`@w_para_flag'),t,`w_paragraph`'')'dnl `undefine(`@w_para_flag')') }}} Hooks for dealing with breaks (`w_softpara' is a hook for those who want to do something for raw `w_para'). {{{ define(`w_softbr',) define(`w_softpara',) }}} Pending blocks. This hook is meant to be invoked for opening a block when (or if) any text is forthcoming. Used by tables (sometimes) and definition lists. {{{ define(`w_pending_block_hook',) define(`w_pending_block', `w_pending_block_hook`'define(`w_pending_block_hook',)') }}} ! Block system !! Block infrastructure This is the real thing. These macros provide the infrastructure for transforming indents and dedents (produced by the indentation system in w_crosslink(s2aimpl.common)) into block structure. Blocks are environments which are opened upon indent and closed upon dedent. If the block type changes, the old block is closed and a new one opened. There is a pseudo block, ''n'', which kind of means "no block at all". It is used because when we get a new indent, we don't know the forthcoming block type (because the indentation system is independent of block types). We store previous block type because sometimes the type of a new block depends on the type of the enclosing block. {{{ w_define_env(n,,) define(`@w_block_type',n) define(`w_indent', `pushdef(`@w_prev_block_type', defn(`@w_block_type'))'dnl `pushdef(`@w_block_type',n)w_beg(n)`'w_indent_hook`'') define(`w_dedent', `w_dedent_hook`'w_end(defn(`@w_block_type'))`''dnl `popdef(`@w_prev_block_type')popdef(`@w_block_type')') }}} Hooks for direct users of the indent system. {{{ define(`w_indent_hook',) define(`w_dedent_hook',) }}} Change block type within indent level. {{{ define(`w_setblocktype', `ifelse(defn(`@w_block_type'),`$1',, `w_end(defn(`@w_block_type'))`'define(`@w_block_type',`$1')'dnl `w_beg(defn(`@w_block_type'))')') }}} !! Block markup glue These definitions transform low-level `w_sbreak', `w_bline', `w_item' and `w_term' into high-level `w_sectbreak', environment invocations, `w_paragraph', `w_listitem' and `w_defnterm'. They use the paragraph system and block system above as well as the indentation system to achieve this. The block types have the following meaning: ''n'':: "no block yet" ''text'':: ordinary text ''q'':: block quote ''-'', ''*'', ''#'', '':'':: itemised, itemised, numbered, and definition lists, respectively. Note that these are _not_ the blocks of the list items, but of the lists themselves. ''-i'', ''*i'', ''#i'', ''t'':: list items. ''t'' is the type of a definition in definition lists (terms in definition lists are not considered blocks at all). Pending block hook usually contains some opening element, if anything. We try to invoke it at an appropriate place: after everything has been closed (so the environments have time to cancel it), but before the elements that were possibly supposed to be within the pending block. Okay, on with the definitions. Section breaks. {{{ define(`w_sbreak', `w_newindent(0)`'w_sectbreak(`$1')') }}} Ordinary text lines. These only induce one level of indentation, whose type is normal text in top level and inside list items, blockquote elsewhere. Kind of like saying, it can remain normal if it has a good reason to be indented so, otherwise it becomes a block quote. {{{ define(`w_bline', `w_newindent(`$1')`'w_onlyindent`''dnl `w_pending_block`'w_beg_para`'w_softbr') define(`w_onlyindent', `ifelse(index(`t-i*i#i',defn(`@w_prev_block_type')),-1, `w_setblocktype(q)',`w_setblocktype(text)')') w_define_env(i,`w_listitem',) }}} Different kinds of list items. These imply the presence of a list; if we were already in a list, the first indent level closes the pending list item. We also mark the indent level of the item text, so we can tell if the next line is a block quote (indented more). {{{ define(`w_item', `w_newindent(`$1',1)`'w_pending_block`'w_setblocktype(`$3')`''dnl `w_newindent(`$1',2)`'w_setblocktype(`$3i')`''dnl `w_newindent(`$2',0)`'w_setblocktype(text)`'undefine(`@w_para_flag')w_softbr') }}} Terms of definition list. These imply the presence of a definition list and a forthcoming definition. However, as the definition text does not begin on this line, we don't set up an indent level for it but just the ''t'' block. {{{ define(`w_term', `w_newindent(`$1',1)`'w_pending_block`'w_setblocktype(:)`''dnl `w_defnterm(`$2')`''dnl `w_newindent(`$1',2)`'w_setblocktype(t)`'undefine(`@w_para_flag')') }}} stx2any/common/emphasis.lsed0000644000175000017500000000421410424125222020071 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.emph)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Different emphasis-like constructs. These must not cross paragraph boundaries and are only recognised in the presence of both an opening and closing marker, so we handle them one paragraph at a time. Literal blocks should be passed untouched. If a literal block was met when gathering a paragraph's lines (see below), it is processed now. {{{ x /^{{{$/ { G x s#.*## } x /^{{{$/,/^}}}$/ b /^{{{\n/,/^}}}$/ b }}} First, gather lines until we reach an empty line or literal block to process emphasis as paragraphs. End of file has to be made a special case. {{{ : gather s# $## $ b nogather N /\n$/ b nogather /\n{{{$/ { s### x s#.*#{{{# x b nogather } b gather : nogather }}} Normalise whitespace. Spaces inserted at the beginning and end of line are taken away later. {{{ s#^# # s#$# # }}} Literal formatting. We previously supported non-quoted versions but the new quote-protection scheme should avoid them altogether. This is quite a regexp because it's complicated to say, in regular expressions, "a span of text not containing the string /X/" (where len(/X/) w_gt 1). {{{ s#\([ \n([{<"-]\)`'w_apo`'`'w_apo`'\([^ `]\(\([^`]\(`'w_apo`'[^`]\)*\(`'w_us`'\)*\(`'w[^_]\)*\(`'[^w]\)*\)*[^ `]\)*\)`'w_apo`'`'w_apo`'\([] \n,.;:?!)}>"-]\)#\1w_literal(`\2')\9#g }}} Underscores have two forms, depending on whether they are already quoted. {{{ s#\([ \n([{<"'-]\)`'w_us`'\([^ `]\(\([^`]\(`'w_apo`'\)*\(`'w[^_]\)*\(`'[^w]\)*\)*[^ `]\)*\)`'w_us`'\([] \n,.;:?!)}>"'-]\)#\1w_emph(`\2')\8#g s#\([ \n([{<"'-]\)_\([^ _]\(\([^_]\(w_\)*\)*[^ _]\)*\)_\([] \n,.;:?!)}>"'-]\)#\1w_emph(`\2')\6#g }}} Other kinds of emphasis. {{{ s#\([ \n([{<"'-]\)/\([^ /]\([^/]*[^ /]\)*\)/\([] \n,.;:?!)}>"'-]\)#\1w_techemph(`\2')\4#g s#\([ \n([{<"'-]\)\*\([^ *]\([^*]*[^ *]\)*\)\*\([] \n,.;:?!)}>"'-]\)#\1w_strong(`\2')\4#g }}} Quotations are processed last to make it possible to have something emphasised within quotes. {{{ s#\([ \n([{<'`-]\)"\([^ "']\([^"]*[^ "]\)*\)"\([] \n,.;:?!)}>'-]\)#\1w_quotation(`\2')\4#g }}} Strip whitespace inserted above. {{{ s#^ ## s# $## }}} stx2any/common/linking.lsed0000644000175000017500000000355210424125232017720 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE This file has definitions for link abbreviations. This is the second phase of processing link abbreviations: the link data has (hopefully) already been gathered by w_crosslink(s2aimpl.gatherlink). The logic of this script is weird. We have complicated rules for deleting link data blocks. The basic difficulty is that both the blocks' beginning and end are marked with empty lines. Whether it is a link data block depends on the line that comes _after_ that. Remove link data blocks. {{{ /^$/,/./{ : del3 /^\[[A-Za-z0-9]\{1,\}\] /,/^$/d /^%-%/b proceed } }}} Generic link syntaces that can be confused with link data blocks. Because labels have not yet been processed, protect against ''+'' as the last character. {{{ s#\[\([^][]*\)\]\[\([^][]*[^][`+]\)\]#`'w_generic_link(`\2', `\1')#g s#^\[\([^][]*[^][`+]\)\]#w_generic_link(`\1')#g }}} Now we don't have anything that could be mistaken for beginning of link data block, so we can jump and see whether this line was actually meant to be deleted (because of the range it's in). {{{ s#^#%-%# b del3 : proceed s#^%-%## }}} Labels. {{{ s#\[+\([^][]*\)+\]#`'w_autolabel(`\1')#g }}} Rest of generic link syntaces. {{{ s#\([^ ,.;:!?"'-]*[^[ ,.;:!?"'-]\)\[\([^][]*[^][`]\)\]#`'w_generic_link(`\2', `\1')#g s#\([ ({<"'.:-]\)\[\([^][]*[^][`]\)\]#\1w_generic_link(`\2')#g }}} URLs. {{{ s#^# # s#\([ ([{<"'-]\)\(https*://[^ ]*[A-Za-z0-9_/]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(ftps*://[^ ]*[A-Za-z0-9_/]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(gopher://[^ ]*[A-Za-z0-9_/]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(nntp://[^ ]*[A-Za-z0-9_/]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(file:/[^ ]*[A-Za-z0-9_]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(mailto:[^ ]*[A-Za-z0-9_]\)#\1w_url(`\2')#g s#\([ ([{<"'-]\)\(news:[^ ]*[A-Za-z0-9_]\)#\1w_url(`\2')#g s#^ ## }}} stx2any/common/gatherlinkmap.lsed0000644000175000017500000000301210424125224021103 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.gatherlink)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE This is a (scary) preprocessor that gathers link data from documents. Link abbreviation processing is two-phase: this is the first phase, before actually processing the documents, in which we just gather enough information for the second phase and ditch everything else. The link data is supposed to be in blocks. Outside blocks, all we have to gather is labels. {{{ /^\[[A-Za-z0-9][A-Za-z0-9]*\] /,/^$/!{ /./!d }}} I don't care to process more than one label per line. If somebody uses two explicit labels on the same line, (s)he can't have a good reason to do so. We read text in whole paragraphs so as to skip blocklike-looking constructs in the middle of a paragraph. {{{ : gulp s#^.*\[+\([^]]*\)+\].*$#w_make_autolabel(`\1')dnl#p s#^!!* *\(.*\)$#w_make_autolabel(`\1')dnl#p $!{ N /\n$/!b gulp } d } }}} End-block processing. {{{ /^$/{ x s#$#`'')dnl#p d } }}} From here on, we are within a link data block. During that, we keep the previous line in hold space. Empty hold space means no line. {{{ s#'#`'w_apo`'#g }}} The case that we have a new datum: see whether there is a line to finish. {{{ /^\[\([A-Za-z0-9][A-Za-z0-9]*\)\] /{ s##define(`@w_linkdata_of_\1',`# x /./!d s#$#`'')dnl#p d } }}} The case that we don't: just store the new one, dump the old one. (Whitespace is stripped to allow indenting line continuations on the same level as the link data marker.) {{{ s#^[ ]*## x }}} stx2any/common/secure.lm40000644000175000017500000000104710424125134017316 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Attempt to kill all possibly dangerous commands. It would be nice to "partially kill" `include' and `undivert', but that does not seem to be possible. Provide some sensible information on what went wrong. {{{ define(`w_gag_cmd', `undefine(`$1')'dnl `define(`$1', `w_warning(`attempt to use "$1" in secure environment')`$1'($@)')') }}} These are the commands to kill. {{{ w_gag_cmd(`builtin') w_gag_cmd(`syscmd') w_gag_cmd(`esyscmd') }}} stx2any/common/block.lsed0000644000175000017500000000333710424125220017355 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.block)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Block rules. These are quite simple: we process line at a time, classifying them by the kind of block-level element they begin. Grouping these into logical entities is done on the ''m4'' side. First, because we want to jump to the end immediately after first matching classification, clear the ''t'' flag of ''sed''. {{{ t foo : foo }}} Basically, there need not be special support for `w_beg' and `w_end'. However, if we process them as their own line type, they won't leave irritating markup in the output (most importantly, no `w_bline') and there is less need for whitespace-related quirks in the implementing ''m4'' code. {{{ s#^\( *\)\(w_invoke(`w_beg')(.*)\) *$#w_newindent(len(`\1'))\2`'dnl# t end s#^\( *\)\(w_invoke(`w_end')(.*)\) *$#w_newindent(len(`\1'))\2`'dnl# t end }}} Next, there are the syntaxes which take the whole line. These don't need a trailing `w_eline'. {{{ s#^\(!!*\) *\(.*\)$#w_headl(len(\1),`\2')# t end s#^ *$#w_para# t end s#^---*$#w_sbreak(len(&))# t end s#^\( *\)\(.*\)::$#w_term(len(`\1'),`\2')# t end }}} Otherwise, add the end-of-line marker. Because this is not a classification, clear the ''t'' flag again. {{{ s#$#`'w_eline# t bar : bar }}} Lists are recognised from the beginning of the line. They induce two indent levels (one for the list, one for the item text) so we report both. {{{ s#^\(\( *\)\* *\)#w_item(len(`\2'),len(`\1'),*)`'# t end s#^\(\( *\)- *\)#w_item(len(`\2'),len(`\1'),-)`'# t end s#^\(\( *\)\# *\)#w_item(len(`\2'),len(`\1'),\#)`'# t end }}} Everything else is an ordinary text line. End of classification. {{{ s#^ *#w_bline(len(`&'))`'# : end }}} stx2any/common/begin.lm40000644000175000017500000000045610424125042017115 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE This is stuff we do just before entering the document(s). Currently not much: just set up the default environment for the document. {{{ w_begdiv(body)dnl w_beg(n)`'w_setblocktype(text)dnl }}} stx2any/common/cleanup.lm40000644000175000017500000000035010424125064017455 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE This is called last. Clear up any unused diversions (otherwise ''m4'' dumps them upon exiting). {{{ divert(-1)undivert }}} stx2any/common/header.lsed0000644000175000017500000000037210424125226017515 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Process header lines into stx2any metadata calls. {{{ 1,/^$/{ /^\([a-z][a-z_]*\): /s/,/`,'/g s/^\([a-z][a-z_]*\): \(.*\)$/w_\1(\2)dnl/ } }}} stx2any/common/common.lm40000644000175000017500000002736210424125107017330 0ustar pkalliokpkalliok00000000000000w_title(stx2any -- common m4 facilities)dnl w_doc_id(s2aimpl.common)dnl w_author(Panu A. Kalliokoski)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) This source file deals with definitions that are generally useful, not directly related to ''stx2any''. You might well want to use these in any ''m4'' based project. First, ignore output. We only want to make definitions; output belongs to (format-specific) templates. {{{ divert(-1) }}} Undefine "format". I wonder what the GNU gurus were thinking about when they defined this extension to be recognised without parameters. {{{ undefine(`format') }}} ! Infrastructure These macros are simple computation or "exception" facilities. !! Error reporting There are 2 error "levels", fatal and non-fatal (ta-da!). Both should report the error location in standard Unix format, because some tools, like ''emacs'', can read this output and directly jump to the error locations. There are two complications: # block-related errors come in pairs, as mismatching begin and end conditions. The "error", which is usually an omission, is at neither place but usually somewhere in between. So, we must report both places. Currently, only the end-place is reported in the standard format. # because the actual input is streamed to ''m4'' through ''sed'', we don't know the actual file names. Fear not: we define the macro `w_real_file' upon entering each input file so we can report errors properly. {{{ define(`w_stdin_p', `ifelse(__file__,stdin,t,__file__,-,t)') define(`w_current_location', `ifelse(w_stdin_p,t,w_real_file,__file__):'dnl `ifelse(w_stdin_p,t,`eval(__line__ - w_line_base)',__line__)') define(`w_warning', `errprint(ifelse(`$2',,`w_current_location',``$2'')`: stx2any: $1'w_nl)') define(`w_error', `w_warning($@)m4exit(1)') }}} !! Output twiddling `w_nl' is indispensable if you want to write neat code. The whitespace dependence in ''m4'' is bad enough as it is. For producing backquotes, we need to override quotes both upon definition and upon invocation. The code looks weird but works. {{{ define(`w_nl',` ') define(`w_void',) define(`w_bq', changequote([[,]])dnl [[changequote(.,.)`changequote(`,')]]dnl changequote(`,')) }}} !! Quote facilities These are needed for storing parameter lists.[[-Single parameters are conveniently handled by simple pushdef / popdef.-]] Combining packs many parameters in a single string; dequoting removes one level of quotes for a string, effectively unpacking the parameter list (parameters are still quoted separately). Actually, ''foo'' is equal to `w_dequote'(`defn'(''foo'')), but only for strings that are valid macro names. For internal variables beginning with ''@'', defn + dequoting is the only way. {{{ define(`w_combine', ``$@'') define(`w_gather', ``$*'') define(`w_dequote', `$1') }}} !! List facilities {{{ define(`w_pickn', `ifelse(`$1',1,`$2',`w_pickn(decr(`$1'),shift(shift($@)))')') define(`w_listlen', `ifelse(`$*',,0,`incr(w_listlen(shift($@)))')') }}} ! Counter system (à la LaTeX) Reentrant newcounter and delcounter. {{{ define(`w_newcounter', `pushdef(`@w_counter_$1',0)'dnl `pushdef(`@w_refcounter_$1',`$2')') define(`w_delcounter', `popdef(`@w_counter_$1')popdef(`@w_refcounter_$1')') }}} All changes to counters are done via setcounter, in order to deal with reference counters. {{{ define(`w_setcounter', `define(`@w_counter_$1',`$2')'dnl `ifelse(defn(`@w_refcounter_$1'),,, `w_setcounter(defn(`@w_refcounter_$1'),0)')') define(`w_getcounter', `defn(`@w_counter_$1')') define(`w_stepcounter', `w_setcounter(`$1',ifelse(`$2',,`incr(',`eval($2+')w_getcounter(`$1')))') }}} Counter value in different formats. {{{ define(`w_counter_arabic', `w_getcounter(`$1')') define(`w_counter_alpha', `substr(_abcdefghijklmnopqrstuvwxyz,w_getcounter(`$1'),1)') define(`w_counter_Alpha', `substr(_ABCDEFGHIJKLMNOPQRSTUVWXYZ,w_getcounter(`$1'),1)') }}} ! Diversion system Diversions are for rearranging input. These are just a thin wrapper around the native diversions of ''m4'', providing nesting, error reporting, and names for diversions. I think naming would be reason enough to use these. Diversions are somewhat hard to understand, because they don't do anything to the way ''m4'' processes macros, they only say where the output goes _when_ there is some output. But in ''m4'', expansions are reread until they don't expand any more; so it's not that simple to tell when there will be output. Stated differently: diversions are _side effects_, so make sure (by quoting) that they won't take effect before you want them to. Another important point to realise is that other side effects (e.g. definitions) are not affected by diversions. {{{ define(`w_begdiv', `ifdef(`@w_div_$1',,`w_error(`unknown diversion "$1"')')'dnl `pushdef(`@w_divlocstack', w_current_location)'dnl `pushdef(`@w_divstack',$1)divert(defn(`@w_div_$1'))') define(`w_enddiv', `ifdef(`@w_divstack',,`w_error(`diversion stack empty')')'dnl `ifelse(`$1',,,`$1',defn(`@w_divstack'),, `w_warning("defn(`@w_divstack')`" begins here...', defn(`@w_divlocstack'))' `w_error(`diversion "'defn(`@w_divstack')`" closed by "$1"')')'dnl `popdef(`@w_divlocstack')popdef(`@w_divstack')'dnl `ifdef(`@w_divstack',`divert(defn(`@w_div_'defn(`@w_divstack')))')') define(`w_check_div', `ifdef(`@w_divstack', `w_error(`unclosed diversion "'defn(`@w_divstack')", defn(`@w_divlocstack'))')') define(`w_dumpdiv', `undivert(defn(`@w_div_$1'))') }}} Diversions are actually numbers. Give some way to map names to those numbers. {{{ w_newcounter(`w_n_avail_div') define(`w_define_div', `w_stepcounter(`w_n_avail_div')'dnl `define(`@w_div_$1', w_getcounter(`w_n_avail_div'))') define(`w_define_trashcan', `define(`@w_div_$1', -1)') }}} ! Environment system (à la LaTeX) Environments are meant for "big" things, where it would be ugly and/or unwieldy to use a single macro. For example, I wouldn't like it if I had to wrap a whole block quote in a macro call. Macros are more sensitive to syntax errors with parentheses and quotes and provide less information about what went wrong. On the other hand, environments can't read and process the included text,[[-unless you are perverse enough to have the environment expand to a big macro call, in which case the problems of macros apply.-]] so the effect of environments is limited to output upon opening and closing, and indirect effects like redefining hooks. That said, environments are a relatively thin wrapper around macro calls, as they are in LaTeX. They provide error reporting, saving of arguments until the end of the environment, and a separate namespace. To allow environments to call other environments, we define many /layers/ of environment variables. Always when we are executing an environment definition, we increase the layer. This ensures that the arguments of the _calling_ environment won't mess with the arguments of the _called_ environment. But this imposes a restriction: environments must always be closed at the same layer where they are opened. {{{ w_newcounter(`w_layer') define(`w_layervar', ``w_layer_'w_getcounter(`w_layer')`_$1'') define(`w_sublayer', `w_stepcounter(`w_layer')$1`'w_stepcounter(`w_layer',-1)') define(`w_define_env', `define(`@w_begin_$1', `$2')define(`@w_end_$1', `$3')') define(`w_ifdef_env', `ifdef(`@w_begin_$1', `$2', `$3')') define(`w_beg', `w_ifdef_env(`$1',, `w_error(`unknown environment "$1"')')'dnl `pushdef(w_layervar(env), `$1')'dnl `pushdef(w_layervar(params), w_combine(shift($@)))'dnl `pushdef(w_layervar(loc), w_current_location)'dnl `w_sublayer(`indir(`@w_begin_$1',shift($@))')') define(`w_end', `ifdef(w_layervar(env),,`w_error(`environment stack empty')')'dnl `ifelse(`$1',,,`$1',defn(w_layervar(env)),, `w_warning("defn(w_layervar(env))`" begins here...', defn(w_layervar(loc)))' `w_error(`environment "'defn(w_layervar(env))`" closed by "$1" in layer 'w_counter_arabic(`w_layer'))')'dnl `w_sublayer(`indir(`@w_end_''defn(w_layervar(env))`,' defn(w_layervar(params))`)')'dnl `popdef(w_layervar(loc))popdef(w_layervar(env))popdef(w_layervar(params))') define(`w_check_env1', `ifdef(w_layervar(env), `w_error(`unclosed environment "'defn(w_layervar(env))`" in layer 'w_counter_arabic(`w_layer'), defn(w_layervar(loc)))')') define(`w_check_env', `w_sublayer(`w_sublayer(`w_check_env1')w_check_env1')w_check_env1') define(`w_push_env', `pushdef(`@w_begin_$1',)pushdef(`@w_end_$1',)') define(`w_pop_env', `popdef(`@w_begin_$1')popdef(`@w_end_$1')') define(`w_make_param_shifter', `ifelse(`$1',0,``$'@',``shift('w_make_param_shifter(decr(`$1'))`)'')') define(`w_derive_env', `w_define_env(`$1', `$4`'w_beg(`$2','w_make_param_shifter(`$3')`)`'$5', `$6`'w_end(`$2','w_make_param_shifter(`$3')`)`'$7')') }}} ! Indentation system (à la Python) The indentation system forms the basis of the block system, because indentation determines the nesting of various elements. Actually, the indents are at least partially virtual. If an element takes a specific indentation, it means that that element wants anything with a greater indentation to be inside it, and with less or equal indentation, outside. All the indentation system does is to translate an indentation level into some or none `w_dedent's possibly followed by a `w_indent'. The work of translating these into element openings and closings is the job of w_crosslink(s2aimpl.markup). We dedent until we can find an enclosing or equal indentation level; then, if we have an enclosing level, we indent onto the requested level. The indentation level consists of two parts: an indent column and a "sub-character" level. Sub-character levels are needed because some constructs may need to open many blocks but only have one sensible column to mark them at. Besides, some constructs (like body text) are outside some others (like lists) even if they begin in the same column. {{{ define(`w_newindent', `ifelse(`$2',,`w_new_indents(`$1',0)', `w_new_indents(`$1',`$2')')') define(`w_new_indents', `w_compare_indent(`$1', `$2', w_dequote(defn(`@w_indstack')), `pushdef(`@w_indstack',`$1,$2')w_indent`'', `popdef(`@w_indstack')w_dedent`'w_new_indents(`$1',`$2')',)') define(`w_compare_indent', `ifelse(eval(`$1>$3'),1,`$5',eval(`$1<$3'),1,`$6', eval(`$2>$4'),1,`$5',eval(`$2<$4'),1,`$6',`$7')') define(`@w_indstack',`0,0') }}} ! List helpers These are facilities to iterate through lists (possibly many times). They are used by some table environments to track column types. {{{ define(`w_setup_list', `pushdef(`@w_list_len_$1', w_listlen(shift($@)))'dnl `pushdef(`@w_list_save_$1', w_combine(shift($@)))'dnl `pushdef(`@w_list_$1', defn(`@w_list_save_$1'))') define(`w_unsetup_list', `popdef(`@w_list_$1')popdef(`@w_list_save_$1')popdef(`@w_list_len_$1')') define(`w_reinit_list', `define(`@w_list_$1', defn(`@w_list_save_$1'))') define(`w_next_in_list', `w_pickn(1,w_dequote(defn(`@w_list_$1')))`''dnl `define(`@w_list_$1',w_combine(shift(w_dequote(defn(`@w_list_$1')))))') define(`w_length_list', `defn(`@w_list_len_$1')') }}} ! Title and other metadata These are not related to any specific markup and are thus defined here. {{{ define(`w_set_or_get', `ifelse(`$2',,`defn(`$1')',`define(`$1', `$2')')') define(`w_doc_id',) define(`w_documentclass',) define(`w_title', `w_set_or_get(`@w_title', `$1')') define(`w_gettitle', `w_title') define(`w_author', `w_set_or_get(`@w_author', `$1')') define(`w_date', `w_set_or_get(`@w_date', `$1')') define(`w_getdate', `w_date') define(`w_language', `define(`@w_language', `$1')'dnl `define(`@w_iso_language', ifelse(`$2',,`substr(`$1',0,2)',`$2'))') define(`w_char_coding', `define(`@w_char_coding', `$1')'dnl `define(`w_long_charset_name', ifelse(`$2',,`w_long_charset_name_for(`$1')',`$2'))') define(`w_long_charset_name_for', `ifelse(`$1',latin9,ISO-8859-15, `$1',ascii,US-ASCII, `$1',utf8,utf-8,ISO-8859-1)') }}} stx2any/common/quote_quotes.lsed0000644000175000017500000000100210424125235021011 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE Do apostrophe quoting before we start doing anything. {{{ t morequ : morequ s#`\([^']*\)'#REALOPENQUOTE\1REALCLOSEQUOTE#g t morequ /`/{ $i\ w_error(Unmatched open quote) N b morequ } s#'#`'w_apo`'#g s#REALOPENQUOTE#`#g s#REALCLOSEQUOTE#'#g }}} Convert tabs into spaces. This is best done in as early a phase as possible, so we don't have to write tabs in our formatting regexps. {{{ s# # #g }}} stx2any/common/templ.lm40000644000175000017500000000031510424125157017153 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ w_dumpdiv(frontmatter)dnl w_dumpdiv(ingr)dnl w_dumpdiv(body)dnl w_dumpdiv(backmatter)dnl }}} stx2any/stx-mode.el0000644000175000017500000001362110424125264016211 0ustar pkalliokpkalliok00000000000000;;; This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski ;;; and released under the license in ../LICENSE (defun stx-bracket-word-with (str) (forward-word 1) (insert str) (backward-word 1) (insert str)) (defun stx-make-bold () "Put in syntax for boldfacing the current word." (interactive) (stx-bracket-word-with "*")) (defun stx-make-italic () "Put in syntax for italicising the current word." (interactive) (stx-bracket-word-with "/")) (defun stx-make-literal () "Put in syntax for making the current word literal." (interactive) (stx-bracket-word-with "''")) (defun stx-make-underline () "Put in syntax for underlining the current word." (interactive) (stx-bracket-word-with "_")) (defun stx-make-heading () "Put in syntax for making a section heading." (interactive) (beginning-of-line) (insert "! ")) (defvar stx-stx2any-args "" "Additional arguments to give to stx2any.") (defun stx-transform-buffer (fmt) "Process the buffer via stx2any. Possible formats are those supported by stx2any, namely: html, man, latex, docbook-xml, xhtml, text, (ps)." (interactive "sOutput format: ") (shell-command-on-region (point-min) (point-max) (concat "stx2any " stx-stx2any-args " -T " fmt) "*stx2any-output*") (switch-to-buffer-other-window "*stx2any-output*")) (defvar stx-preview-command "groffer" "Command to use for previewing postscript.") (defun stx-preview-buffer-as-webpage () "Preview the buffer as converted to a web page, via browse-url." (interactive) (let ((myfile (make-temp-name "/tmp/stx2any"))) (shell-command-on-region (point-min) (point-max) (concat "stx2any " stx-stx2any-args " -T html >" myfile)) (browse-url (concat "file://" myfile)))) ;;;###autoload (defun stx-preview-buffer () "Preview the buffer as it would be printed by stx-print-buffer. The actual command used for previewing can be set by the variable stx-preview-command." (interactive) (stx-send-buffer "man" stx-preview-command)) ;;;###autoload (defun stx-print-buffer () "Print the buffer via stx2any, groff and lpr. The actual command used for printing can be set by the variable lpr-command." (interactive) (stx-send-buffer "ps" lpr-command)) (defun stx-send-buffer (fmt command) "Helper function for stx-preview-buffer and stx-print-buffer." (shell-command-on-region (point-min) (point-max) (concat "stx2any " stx-stx2any-args " -T " fmt " | " command))) (defvar stx-mode-map (let ((mymap (make-sparse-keymap))) (define-key mymap "\C-c\C-c" 'stx-transform-buffer) (define-key mymap "\C-c\C-p" 'stx-preview-buffer) (define-key mymap "\C-cp" 'stx-print-buffer) (define-key mymap "\C-cb" 'stx-make-bold) (define-key mymap "\C-ci" 'stx-make-italic) (define-key mymap "\C-cl" 'stx-make-literal) (define-key mymap "\C-cu" 'stx-make-underline) (define-key mymap "\C-ch" 'stx-make-heading) (define-key mymap [menu-bar stx] (cons "Stx" (make-sparse-keymap "Stx"))) (define-key mymap [menu-bar stx stx-make-bold] '(menu-item "Make a word bold" stx-make-bold)) (define-key mymap [menu-bar stx stx-make-italic] '(menu-item "Make a word italic" stx-make-italic)) (define-key mymap [menu-bar stx stx-make-literal] '(menu-item "Make a word literal" stx-make-literal)) (define-key mymap [menu-bar stx stx-make-underline] '(menu-item "Underline a word" stx-make-underline)) (define-key mymap [menu-bar stx stx-make-heading] '(menu-item "Make current line a heading" stx-make-heading)) (define-key mymap [menu-bar stx stx-preview-buffer-as-webpage] '(menu-item "Preview as web page" stx-preview-buffer-as-webpage)) (define-key mymap [menu-bar stx stx-print-buffer] '(menu-item "Print buffer" stx-print-buffer)) (define-key mymap [menu-bar stx stx-preview-buffer] '(menu-item "Print preview" stx-preview-buffer)) (define-key mymap [menu-bar stx stx-transform-buffer] '(menu-item "Convert buffer" stx-transform-buffer)) mymap) "Keymap for Stx major mode.") (defvar stx-list-marker-regexp "^ *[-*#] ") (defvar stx-hard-divisor-regexp "^\\(---*\\|{{{\\|}}}\\)$") (defvar stx-paragraph-separate (concat "[ \t]*$\\|" (substring stx-hard-divisor-regexp 1) "\\|!\\|.*::$") "Regexp to match paragraph separators in Stx.") (defvar stx-paragraph-start (concat stx-paragraph-separate "\\|" (substring stx-list-marker-regexp 1)) "Regexp to match paragraph starts or separators in Stx.") (defvar stx-font-lock-keywords (append (list (cons stx-list-marker-regexp 'font-lock-builtin-face) (cons stx-hard-divisor-regexp 'font-lock-builtin-face)) '(("w_[a-z_]*\\|\\(un\\)?define\\|dnl" . font-lock-keyword-face) ("\\[\\[[- ]\\|[- ]\\]\\]\\| -- " . font-lock-builtin-face) ("[A-Za-z0-9)]\\(--\\)[(A-Za-z0-9]" 1 font-lock-builtin-face) ("\\(//\\|::\\)$" . font-lock-builtin-face) ("\\(^\\|[ (\"'-]\\)/\\([^ /][^/]*\\)/\\($\\|[ ,.;:?!)\"'-]\\)" 2 font-lock-type-face) ("\\(^\\|[ (\"'-]\\)\\*\\([^ *][^*]*\\)\\*\\($\\|[ ,.;:?!)\"'-]\\)" 2 font-lock-comment-face) ("\\(^\\|[ (\"'-]\\)_\\([^ _][^_]*\\)_\\($\\|[ ,.;:?!)\"'-]\\)" 2 font-lock-type-face) ("\\(^\\|[ (\"-]\\)''\\([^ '][^']*\\)''\\($\\|[ ,.;:?!)\"-]\\)" 2 font-lock-string-face) ("`\\([^']\\)'" . font-lock-constant-face) ("^\\(!!*\\)\\(.*\\)$" (1 font-lock-builtin-face) (2 font-lock-comment-face)))) "Faces for Stx fontification.") (defvar stx-mode-hook '() "Hooks to run upon entering Stx major mode.") ;;;###autoload (defun stx-mode () "A major mode for editing Stx (structured text) documents." (interactive) (kill-all-local-variables) (use-local-map stx-mode-map) (make-local-variable 'font-lock-defaults) (make-local-variable 'paragraph-start) (make-local-variable 'paragraph-separate) (setq major-mode 'stx-mode mode-name "Stx" font-lock-defaults '(stx-font-lock-keywords t) paragraph-start stx-paragraph-start paragraph-separate stx-paragraph-separate) (turn-on-font-lock) (auto-fill-mode 1) (run-hooks 'stx-mode-hook)) stx2any/docbook-xml/0000755000175000017500000000000010446213102016333 5ustar pkalliokpkalliok00000000000000stx2any/docbook-xml/make.lm40000644000175000017500000001326310424125170017676 0ustar pkalliokpkalliok00000000000000w_doc_id(s2aimpl.docbook-xml)dnl This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE w_use(examples/reflection-disclaimer) Definitions for DocBook XML. XML requires well-formed paragraphs, so we have our own paragraph system here. We put a paragraph inside most everything "just to be sure". Here are the macros to keep the result well-formed. {{{ define(`w_paragraph', `w_closedefine(`@w_para_open',t)') define(`w_open', `w_paragraph`'undefine(`@w_para_flag')') define(`w_close', `ifelse(defn(`@w_para_open'),t,)'dnl `define(`@w_para_open',)') }}} `w_close' must be called before emitting any block-level tag. `w_open' will open a paragraph, no matter what. `w_softopen' marks that if there is text forthcoming, it must be in its own paragraph. DocBook has its own sectioning system -- very structured but poorly corresponding to traditional typography. (In some ways, a section is a unit, in others, it is not. For example, a document usually makes sensible reading if you take away headings, but not always when you remove some section.) The macros here are linked to headings: headings produce sections. But we need to hook closing of sections somewhere. This is done at the template. {{{ define(`@w_sectlev', 0) define(`w_set_sect_level', `ifelse(eval(`$1>'defn(`@w_sectlev')),1, `define(`@w_sectlev',incr(defn(`@w_sectlev')))'dnl `w_closew_set_sect_level(`$1')', eval(`$1<'defn(`@w_sectlev')),1, `w_closew_softopen`'define(`@w_sectlev', decr(defn(`@w_sectlev')))w_set_sect_level(`$1')')') define(`w_headline', `w_set_sect_level(decr(`$1'))'dnl `w_set_sect_level(`$1')$2w_softopen') }}} Block system environments. {{{ w_define_env(-,`w_close',`w_closew_softopen') w_define_env(#,`w_close',`w_closew_softopen') w_define_env(i,`w_closew_open',`w_close') w_define_env(q,`w_close
    w_open',`w_close
    w_softopen') w_define_env(:, `w_closepushdef(`@w_varitem_open',)', `w_close`'w_close_varitempopdef(`@w_varitem_open')w_softopen') define(`w_defnterm', `w_open_varitem$1') w_define_env(t, `define(`w_pending_block_hook', `w_closew_open')', `ifelse(defn(`w_pending_block_hook'),, `w_closew_close_varitem', `define(`w_pending_block_hook',)')') define(`w_open_varitem', `ifelse(defn(`@w_varitem_open'),,`w_close')'dnl `define(`@w_varitem_open',t)') define(`w_close_varitem', `ifelse(defn(`@w_varitem_open'),t,`w_closew_softopen`'')'dnl `define(`@w_varitem_open',)') }}} Other environments. {{{ w_define_env(litblock,`w_close',`w_closew_softopen') w_define_env(footnote,`',`') w_define_env(compactlist, `w_closew_open', `w_closew_softopen') w_define_env(center, `w_closew_open', `w_closew_softopen') w_define_env(abstract, `w_close`'w_begdiv(ingr)w_open', `w_closew_enddiv(ingr)w_softopen') w_define_env(comment, `') w_define_env(citation, `w_close
    $*w_open', `w_close
    w_softopen') w_define_env(`w_float_n', `w_close
    w_softopen', `w_caption(`$1') w_close
    w_softopen') }}} There is no real way to put line breaks into documents in DocBook. We should wrap the whole paragraph in literal layout, but we can't do that at this stage, and there might be non-hard line breaks in the same paragraph. Let's just settle for this ugly hack: {{{ define(`w_linebr', w_nl) }}} Emphasis. {{{ define(`w_literal', `$1') define(`w_emph', `$1') define(`w_techemph', `$1') define(`w_strong', `$1') define(`w_quotation', `$1') }}} Other inlines. {{{ define(`w_link', `$2') define(`w_url', `$1') define(`w_img', `' `' `$2' `') define(`w_label', `'dnl `ifdef(`w_symmetric_crossrefs',`$2',`$2')') define(`w_refer', `ifdef(`w_symmetric_crossrefs',`')'dnl `$2') }}} Tables. {{{ define(`w_make_tablespec', `ifelse(`$*',,,`'dnl `w_make_tablespec(shift($@))')') w_define_env(w_table, `pushdef(`w_caption', `$1')'dnl `w_closew_make_tablespec($@)w_nl', `w_closepopdef(`w_caption')w_softopen`'') w_define_env(w_row, `w_close', `w_close') w_define_env(w_cell, `w_close', `w_close') define(`w_table_rule',) dnl TODO? }}} Admonitions. {{{ w_define_env(`admonition', `w_close`'ifelse(w_standard_admonition(`$1'),t,`<`$1'>',``$1':')w_open', `w_close`'ifelse(w_standard_admonition(`$1'),t,`',`')w_softopen') define(`w_standard_admonition', `ifelse(index(`Note,Tip,Caution,Warning,Important',`$1'),-1,,t)') }}} Special and quoted characters. {{{ define(`w_lt', `<') define(`w_gt', `>') define(`w_amp', `&') define(`w_emdash', `—') define(`w_endash', `–') define(`w_ellipsis', `…') define(`w_copyrightsign', `©') define(`w_trademarksign', `™') define(`w_larrow', `←') define(`w_rarrow', `→') }}} stx2any/docbook-xml/settings.lsh0000644000175000017500000000033010424125240020700 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ test -z "$NUMBERING" && NUMBERING=off TABLE_OF_CONTENTS=off test -z "$PIC_SUFFIX" && PIC_SUFFIX=png }}} stx2any/docbook-xml/templ.lm40000644000175000017500000000112510424125173020077 0ustar pkalliokpkalliok00000000000000This file is copyright (c) 2004,2005,2006 by Panu Kalliokoski and released under the license in ../LICENSE {{{ defn(`@w_title') defn(`@w_author') w_dumpdiv(frontmatter)dnl w_dumpdiv(ingr)dnl w_dumpdiv(body)dnl w_dumpdiv(backmatter)dnl w_close`'w_set_sect_level(0) }}} stx2any/examples/0000755000175000017500000000000010471044066015744 5ustar pkalliokpkalliok00000000000000stx2any/examples/stx2any.txt0000644000175000017500000003013410471044066020116 0ustar pkalliokpkalliok00000000000000w_title(stx2any)dnl w_doc_id(s2aman)dnl w_section(1)dnl w_author(Panu A. Kalliokoski)dnl w_man_desc(converter from structured text to multiple formats) ! SYNOPSIS ''stx2any'' [ -T /format/ ] [ /stx and m4 options/ ] [ /file/ /file/ ... ] ! DESCRIPTION ''stx2any'' converts files in structured text (Stx) format into other formats. Formats currently implemented are HTML, man, raw text, PostScript, LaTeX, XHTML and DocBook XML. The source format, structured text, is a kind of plain text format with standard markup for representing headings, lists, emphasis etc. The markup is both quicker to write and easier to remember than conventional tag-based markup languages, and is beautifully legible also in source form. Stx markup is better explained in _Stx quickie guide_, which is available in the ''examples'' directory. Most of the conversion happens in ''m4'', and you can define your own macros and other stuff for giving structure to your documents. ''stx2any'' provides a LaTeX-like extensible environment system and a diversion system for rearranging input. (Tårta på tårta, as they say in Swedish.) Because ''stx2any'' doesn't perform any kind of quoting on the input, markup that isn't available can be written directly in the destination language (losing convertibility to multiple languages). This way, if you are only interested in one output format (eg. LaTeX), you can use Stx as an abbreviation format for the most common constructs. Some formatting is not available as abbreviations, but by calling m4 macros. You need macros relatively rarely: for example, floats (material that can "float" around in the document) are created by macros. ! OPTIONS ''stx2any'' accepts all command line options of ''m4'', passing them directly on. Of these, the ''-D'' argument is important enough to mention here separately. ''-DNAME=VALUE'':: Define macro NAME to have the expansion VALUE. This allows you to pass information into the document from the command line. ''-T /format/'':: Sets the output format. Default format is ''html''. /format/ should be one of: html:: produces basic HTML (hypertext markup language) output. man:: produces man macro output. This output is usable as a man page directly (although see WRITING MAN PAGES below), or can be fed to ''troff'' / ''groff'' for formatting to e.g. postscript. latex:: produces LaTeX document preparation language output. You can run ''latex'' on the result to produce e.g. high quality pdf's. text:: produces raw text output by postprocessing HTML output with ''w3m''. The resulting output is very basic, like stripping away most Stx markup; if you want more formatted output, consider piping man output to ''nroff -man''. ps:: produces simple postscript output by postprocessing man output with ''groff''. If you want to do real publishing, consider the LaTeX format instead. xhtml:: produces XHTML output by postprocessing HTML output with W3C ''tidy''. By the way, check w_url(http://hixie.ch/advocacy/xhtml) for discussion about HTML and XHTML. docbook-xml:: produces rudimentary DocBook XML output. See BUGS below for more discussion about this. ''--link-abbrevs'':: Take link abbreviation syntax into use. Note that because link abbreviation processing occurs in two phases, it doesn't work totally when the input comes from standard input (for example, if you use ''stx2any'' as a middle part of a pipeline). ''--quote'':: Request quoting of characters (other than underscores and dollar signs) that are somehow magical in the requested output format. This will make it quite difficult to put markup in the output format directly in your document, but will greatly increase the possibility that your document will be correct (ie. does not have syntax errors) in the output format. ''--quote-me-harder'':: Request quoting of underscores and dollar signs. This might make some LaTeX documents work but might break some documents where underscores are used in macro names or dollar signs in macro definitions. ''--numbering { on | off }'':: Request numbering of section headings. The default varies by output format: section numbering is by default ''off'' for HTML, DocBook XML and man, ''on'' for LaTeX. ''--table-of-contents { on | off }'':: Request producing a table of contents from the headings. The default is to produce a TOC when numbering is on. Not implemented for DocBook XML. ''--make-title { on | off }'':: Request a "title page". The default is "on". This setting does not have any effect in some formats. In HTML, it produces a big heading at the beginning of the document. In LaTeX, it produces the canonical maketitle. ''--no-template'':: Do not produce a document template at all, only the formatted input text. You probably need this if your document will be included as a part of a bigger document. If that bigger document is written totally in Stx, however, it will be cleaner to give all the source files directly as arguments to ''stx2any'' rather than combine the results afterwards. ''--symmetric-crossrefs'':: In document formats that support linking (HTML, DocBook), produce reverse links from labels to referrers as well as links from referrers to labels. ''--latex-params /params/'':: Set the document class parameters for LaTeX documents. The default is affected by system paper size; for example, on a European system it is typically ''a4paper,notitlepage''. (See "ENVIRONMENT" below.) ''--html-params /params/'':: Set the body tag parameters for HTML documents. The default is no parameters. ''--picture-suffix /suffix/'':: Inline images will refer to files with suffix /suffix/. The default is ''png'' for HTML and DocBook, ''eps'' for LaTeX and man. ''--no-emdash-separate'':: In the output, don't separate em dashes from adjacent text with spaces. This is in accordance to traditional English typography (if I understand correctly), but is not standard in many other languages -- including Finnish, my mother tongue. ''--more-secure'':: Disable some insecure features of m4 and check some command line arguments that are passed to shell for problematic characters. This might be desirable if you've received the document from somewhere else and want to make sure it won't do anything malicious when converted. Currently this denies execution of shell escapes. Note that clearly no implementation of m4 has been designed with security in mind. As a consequence, this option cannot prevent every potentially harmful thing. Things not prevented which I'm aware of are including contents of arbitrary files in the output and writing busy loops (so that the conversion will use all processor time it can get, until terminated). ''--sed-preprocessor /scriptname/'':: Run the sed script /scriptname/ for all input. This allows you to add custom abbreviation markups. It is almost the same as preprocessing input with ''sed'', then piping it into ''stx2any'', but interacts better with ''--link-abbrevs'' (see its explanation for details). ''--version'', ''-V'':: Just show version information and exit. ''--help'', ''-?'':: Just show a short help message and exit. ! WRITING MAN PAGES Basically, man pages are simply files in the man macro format. However, there are some programs (first and foremost ''mandb'') that require parts of man pages to be in a specific format, and man pages should generally adhere to the standard sectioning and form (see ''man'' (1) and ''lexgrog'' (1) for details). When writing a man page, the title (`w_'title) of the page should be the program/file/format/utility name, and you should define the section (`w_'section). To make the page suitable for ''mandb'' parsing, you should start the page with one or more calls to `w_'man_desc. This will create a proper "NAME" section for you. (Although you could write one by yourself.) ! DIAGNOSTICS ''stx2any'' may give any error message that ''m4'' may give, e.g. on malformatted input (a macro call with missing closing parenthesis etc). In addition, it has the following own error messages: unknown output format: "X":: You requested unsupported output format /X/ with the ''-T'' option. unknown macro "X" called:: ''stx2any'' encountered a macro beginning with ''w_'', but knows no definition for it. This is a warning, not an error -- the offending macro and its arguments are stripped from the output. environment "X" closed by "Y" in layer N:: Environments in ''stx2any'' must be properly nested. ''stx2any'' encountered w`_'end(/Y/) when it was expecting w`_'end(/X/). Often this is a sign of a forgotten w`_'end(/X/). If /N/ (the layer) is something other than 0, then the problem is probably in your environment definitions, not at the point that ''stx2any'' was processing when it encountered the error. unknown environment "X":: There was an attempt to begin an environment whose name is unknown to ''stx2any'', i.e. no such environment has been defined. diversion "X" closed by "Y":: unknown diversion "X":: Same as above, but for diversions (w`_'begdiv and w`_'enddiv). attempt to use "X" in secure environment:: You requested secure processing with ''--more-secure'' and the document contained an "insecure" macro. This is a warning message, not an error -- the causing macro is left in the text verbatim. unknown cross link to "X":: There was a cross link to document /X/, but ''stx2any'' does not know about such a document. Probably you didn't gather /X/'s data with ''gather_stx_titles'' or you misspelled the document reference. This is a warning, not an error -- the reference is left in the output verbatim, without any kind of link. The return value of ''stx2any'' is zero on success, one if there was some problem. ! ENVIRONMENT PAPERCONF:: PAPERSIZE:: used for determining the default paper size for LaTeX documents. ! FILES ''/etc/papersize'':: used for determining the default paper size for LaTeX documents. ''PREFIX/share/stx2any/common'':: directory for the definitions shared by all formats ''PREFIX/share/stx2any/{html,man,latex,docbook-xml}'':: directory for output format specific definitions ! SEE ALSO ''m4'' (1), ''latex'' (1), ''groff'' (1), ''lexgrog'' (1), ''w3m'' (1), ''strip_stx'' (1), ''gather_stx_titles'' (1), ''html2stx'' (1), ''extract_usage_from_stx'' (1) // _Stx quickie guide_ (''PREFIX/share/doc/stx2any/Stx-doc.txt'') // _Stx markup reference_ (''PREFIX/share/doc/stx2any/Stx-ref.txt'') ! BUGS The structured text format is not yet fully standardised. There are some corner cases where it is unclear what the result of the formatting should be. In these cases, the output of ''stx2any'' is authoritative, so it /cannot/ have bugs :) Some old GNU libc's seem to be abysmally slow on some instances of the emphasis regexps. It would be possible to make the regexps faster and less correct, but as newer GNU libc's and BSD libc seem to work OK in these cases, I guess it's not worth it. The ''--more-secure'' switch is not really very secure for reasons explained above. The support for DocBook XML sucks. It is only included because someone will show up anyway and ask, "hey, does it support *DocBook XML*?" Partly this sucking is due to my laziness, but partly it is because of the nature of DocBook. For instance, ''stx2any'' will transform literal formatting into DocBook Literal elements, but the _point_ of using DocBook is to convey more information than that -- whether it is some ComputerOutput, UserInput, EnVar, or Application, or... and the result is still very abstract, not actually meant for humans to read but rather for computers to process into something readable. Now the truth is that I doubt you will ever come up with a DSSSL stylesheet whose output outperforms LaTeX (for publishing on paper) or direct conversion to HTML (for publishing on the web). The only sensible reasons I can think of for using Stx as a DocBook frontend are: # the ability to use both DocBook constructs and Stx abbreviations # if you have to write DocBook for some interesting reason (your boss told you so) but don't want to learn it # you happen to already have infrastructure for processing DocBook documents, and you want to take advantage of it ! AUTHOR This page is written by w_author. stx2any/examples/Stx-doc.txt0000644000175000017500000001361610423671243020035 0ustar pkalliokpkalliok00000000000000title: Stx quickie guide author: Panu Kalliokoski date: 25.1.2006 language: english (You may want to look at the source[./Stx-doc.txt] of this file.) You can set various document metadata at the beginning of the file. The most important items can be seen above. Usually, you will want to give your text some structure with headings. The lines beginning with exclamation points are headings. The number of exclamation points determines the level of the heading: one means top-level heading, two means subheading, three means sub-subheading and so on. ! Paragraphs and whitespace !! Basic paragraphs For most part, you can use whitespace (spaces, tabs, and line breaks) the way you want to. There are two notable exceptions: # an empty line marks a paragraph break. # the amount of indentation of a line affects Stx's idea of where the line belongs. The text of every line in a paragraph should be indented to the same column. Because Stx doesn't generally care about the way you use whitespace, if you want to preserve the formatting of the source, you need to request it separately. !! Preformatted text Three open curly braces ({{{) begin a preformatted text block, and three close curly braces (}}}) end it: {{{ This is preformatted text. }}} !! Line breaks To force a line break at a certain point in text, // end a line with double-slash ''//''. This will begin // a new line // immediately. ! Inline markup Inline markup is what you put in your document to cause textual effects. !! Emphasis There are two kinds of emphasis, _normal_ and *strong*. _Normal emphasis_ is achieved by bracketing the phrase with underscores ''_'' or slashes ''/'' -- the choice is free.[[ Actually, underscores are meant for "semantic" emphasis (marking a phrase especially noteworthy) whereas slashes are meant for "technical" emphasis (first occurrences of terms, titles of cited works, text that is not to be taken literally). ]] *Strong emphasis* is given by bracketing with asterisks ''*''. Additionally, there is a special kind of emphasis that typesets the text in ''teletype font''. !! Footnotes You can add footnotes[[ A footnote is a short comment to the text. ]] to the text by putting the footnote into double brackets (''[['' and '']]''). The footnote text must be separated from the brackets with a space ( ) or a dash (-). !! Special characters Enclose quotations in quotation marks ''"'' to produce the right formatting. An upper- or lowercase "c" in parentheses ''(c)'' produces a copyright sign, and ''(tm)'' produces a trademark sign. Two dashes in a row ''--'' produce "long dashes". !! Links If you enable link abbreviations (see [Stx-ref.html]), many expressions with brackets become links. Link data can be written right into the link[http://example.com/like-this/], or placed indirectly into a [link data block][fn1]. Another example[ln1]. You can also point to sectional units, such as [Sectioning]. [fn1] This is link data for the indirect link reference "fn1". Because it does not look like anything link-like, it will be made into a footnote. [ln1] http://example.com/indirect-link/ ! Block-level markup !! Sectioning A horizontal line can be achieved by putting two or more dashes ''--'' on a line by themselves: --- But most of the time, you will only want to use headings for sectioning. !! Lists Lists give a document structure. Overuse of lists (demonstrated below) makes a document seem technical and reference-like. There are three kinds of lists: # enumerated (such as this one) # itemized (the same, only with bullets instead of numeric labels) # term-definition lists (such as the following one) What are they good for and how do you write them? Itemized lists:: Very basic, general-purpose construct. You can often make notes by writing an ad-hoc itemised list. Subpoints can be added by making a sublist (lists can be nested within one another by indentation): - note 1. - note 2. - subnote 2.1 By the way, list items can have many paragraphs, too. As well as all other kinds of constructs, as long as you indent them relative to the list. - another point. If the item is very long and you add a line break, the lines must be indented properly. In itemised lists, you can use the dash (''-'') or the asterisk (''*'') as a list marker, but not within the same list. Term-definition lists:: These are good for producing e.g. * list-like descriptions of different things * word lists and the like * link menus with comments * short textual blurbs which are naturally divided by subject Term-definition lists are a very versatile construct, and underused by many. If your list items are short and/or stand by themselves, you can use ordinary lists, but if you want to attach comments to the items, you are usually better off using term-definition lists. For term-definition lists, the double-colon (''::'') at the end of a line is the magic marker that causes a line to turn into a term. A definition is anything that follows a term, indented. Enumerated lists:: # look somehow very official and precise. # written similarly to itemised lists, with a hash sign (''#'') as the list marker. # handy if the items of the list have some kind of preference or timeline order. # not good for giving lists to whose items you can refer: - adding items into the middle of the list changes the numbering of the rest of the items. - you can't know anyway how your list gets numbered in different output formats with different styles. !! Quotes An indented paragraph is taken to be a citation block. Citations, too, can be nested within one another and lists. Those were the days, my friend, // I hope w_beg(comment) or is it "thought"? w_end(comment) they'd never end.. Citation blocks are also good for indenting things that should stand out, such as mathematical formulae, examples, and noteboxes. stx2any/examples/extract_usage_from_stx.txt0000644000175000017500000000270710471044066023272 0ustar pkalliokpkalliok00000000000000w_title(extract_usage_from_stx)dnl w_doc_id(eufsman)dnl w_author(Panu A. Kalliokoski)dnl w_man_desc(`extract "Usage:" messages from manpages written in Stx') ! SYNOPSIS ''extract_usage_from_stx'' [ /file/ /file/ ... ] ! DESCRIPTION Process the given /files/, which should be manpages written in Stx, stripping away everything that is typically _not_ included in a "Usage:" message. If no /files/ are given, read standard input instead. A "Usage:" message is a message typically printed when a program is called with incorrect arguments or when help is specifically requested, for example with a ''--help'' command line option. A "Usage:" message is typically a subset of the information provided on a command's manual page. The information left in the "Usage:" message by ''extract_usage_from_stx'' includes: - the command synopsis, as given in the "SYNOPSIS" section - the command line options, as given in the "OPTIONS" section, together with the first sentence of their description. A sentence is taken to end at a period (''.''). The output of ''extract_usage_from_stx'' is still in Stx format, which you might want to further process to produce the actual "Usage:" message. ! OPTIONS ''--version'', ''-V'':: Just show version information and exit. ''--help'', ''-?'':: Just show a short help message and exit. ! SEE ALSO ''stx2any'' (1). ! BUGS The end-condition of a sentence is too strong. ! AUTHOR This manual page was written by w_author. stx2any/examples/gather_stx_titles.txt0000644000175000017500000000530110471044066022240 0ustar pkalliokpkalliok00000000000000w_title(gather_stx_titles)dnl w_doc_id(gstman)dnl w_section(1)dnl w_author(Panu A. Kalliokoski)dnl w_man_desc(gather title declarations from Stx documents) ! SYNOPSIS ''gather_stx_titles'' [ -f /from-suffix/ ] [ -t /to-suffix/ ] [ /m4 options/ ] /file/ [ /file/ ... ] ! DESCRIPTION ''gather_stx_titles'' digs out Stx metadata declarations from the listed /files/, and dumps the title and document ID information as ''m4'' definitions into standard output. This information can later be used by w`_'crosslink to link the documents by their metadata. Why is this useful? Well, imagine that you have a large site with a lot of cross-linking. A document's name will appear in many places: in the link menu (if you have one), and in the body of different pages where it is cross-linked from. ''gather_stx_titles'' lets you put all the information in one place and where it belongs, i.e. the file itself. You'll be glad if you did, when the time comes to change document titles or move the documents around; especially so if your website has multilingual magic. ! OPTIONS ''gather_stx_titles'' uses ''m4'' internally and will accept any option ''m4'' accepts. In addition to those, it takes the following options: ''-f /from-suffix/'':: In the filename data, substitute away the suffix /from-suffix/. Actually, /from_suffix/ may be a regular expression; stupid but true, in GNU ''m4'' it is a "traditional" regexp, whereas in BSD ''m4'' it is an "extended" regexp. Default to no suffix (nothing to take away). ''-t /to-suffix/'':: In the filename data, substitute the suffix taken away by /from-suffix/ with /to-suffix/. If /from-suffix/ is nil (the default), append /to-suffix/ to all filenames. ''-p /prefix/'':: Strip away the prefix given by (regular expression) /prefix/ from filenames. The equivalent of ''-t'' for this does not exist, because you can specify a directory prefix to `w_crosslink' by `w_base'. ''--version'', ''-V'':: Just show version information and exit. ''--help'', ''-?'':: Just show a short help message and exit. ! EXAMPLES I guess most of the time you will want to automate the use of ''gather_stx_titles'', for example with a ''Makefile'' like this: {{{ SOURCES = $(wildcard *.stx) TARGETS = $(SOURCES:.stx=.html) all: $(TARGETS) titles.m4: $(SOURCES) gather_stx_titles -f stx -t html $^ > $@ %.html: %.stx titles.m4 stx2any -T html titles.m4 $< > $@ }}} If you don't want to be quite so correct, drop the ''.html'' dependency on ''titles.m4'' or ''titles.m4'' dependency on ''SOURCES''. Using temporary files is not necessary: this should also work: {{{ $ gather_stx_titles `*'.stx | stx2any - mydoc.stx }}} ! SEE ALSO ''stx2any'' (1). ! AUTHOR This page is written by w_author. stx2any/examples/html2stx.txt0000644000175000017500000000245010471044066020273 0ustar pkalliokpkalliok00000000000000w_title(html2stx)dnl w_doc_id(h2sman)dnl w_section(1)dnl w_author(Panu A. Kalliokoski)dnl w_man_desc(convert HTML documents into Stx) ! SYNOPSIS ''html2stx'' [ /file/ ] ! DESCRIPTION ''html2stx'' takes the given /file/, which should contain an HTML document, and converts it to structured text (Stx). If no file is given, standard input is read instead. The program does not attempt to convert every possibly convertible piece of markup into Stx. For example, w_lt`'font`'w_gt tags are simply ignored. This tends to result in a nice, clean, beautiful document. (If it doesn't, the source document probably does not contain enough information to start with.) ! OPTIONS None. ! DIAGNOSTICS ''html2stx'' is a python script and will throw an exception if something goes amiss. In this case, the return value will be non-zero. ! SEE ALSO ''stx2any'' (1), w_crosslink(Stx-ref.html) ! BUGS - The word wrapping algorithm is probably not very clever. - Sometimes there are extra linebreaks in the output. - Probably many others. ! AUTHOR This manual page was written by w_author. ''html2stx'' is derived from the ''html2text'' utility by Aaron Swartz. ''html2text'' is a utility for converting html into "Markdown" structured text; the changes required to make it work for Stx were done by Panu Kalliokoski. stx2any/examples/reflection-disclaimer.m40000644000175000017500000000066710423671243022463 0ustar pkalliokpkalliok00000000000000It is quite impossible to make the w_literal(m4) definition files render properly under w_literal(stx2any). The reason is that, in order to do so, we should switch w_literal(m4) processing off within literal blocks, which we cannot. (Besides, the end of a literal block is marked by w_literal(m4) markup.) w_paragraph`'But anyway, I hope that these files will serve as good documentation already in source form. Have fun reading them. stx2any/examples/strip_stx.txt0000644000175000017500000000431510471044066020547 0ustar pkalliokpkalliok00000000000000w_title(strip_stx)dnl w_doc_id(ssman)dnl w_section(1)dnl w_author(Panu A. Kalliokoski)dnl w_man_desc(a simple literate programming tool) ! SYNOPSIS ''strip_stx'' [ -c /commentchars/ ] [ -B /open/ /close/ ] [ /file/ /file/ ... ] ! DESCRIPTION ''strip_stx'' takes all structured text (Stx) markup away from the listed /files/, leaving only text in preformatted blocks. If no files are listed, standard input is read instead. The result is written to standard output. This is intended as a simple literate programming tool: programmers may write their programs as documents, processing them with ''stx2any'' for documentation and publication but with ''strip_stx'' for compilation / running the code. More information about Stx is on the manpage of ''stx2any''. ! OPTIONS ''-c /commentchars/'':: comment out the non-code portions (text outside preformatted blocks) with the given /commentchars/ at the beginning of every line. If this option (or the next one) is not given, non-code portions are simply deleted. ''-B /open/ /close/'':: surround the non-code portions with (comment-)opening and closing markers /open/ and /close/ respectively. This option can be used together with the ''-c'' option. ''--version'', ''-V'':: Just show version information and exit. ''--help'', ''-?'':: Just show a short help message and exit. ! EXAMPLES ''strip_stx parse.py.stx w_gt parse.py'' Strip documentation away from the source file ''parse.py.stx'', supposedly only leaving python code there. ''strip_stx -B '/*' ' */' -c ' * ' my.c.stx w_gt my.c'' Make a literate C code document into proper C source file, leaving the documentation in neatly-formatted comments. ''strip_stx -B 'cat w_lt w_lt EOT' 'EOT' embshell.stx w_gt embshell.sh'' Turn the document ''embshell.stx'' into an "embedded shell" script, where all non-program portions are printed to the standard output when execution reaches them. This is akin to PHP or eperl; but ''strip_stx'' is not really meant for this. There are other options for making embedded scripts, such as defining your own markup for the code portions or handling the program logic with ''m4'' within ''stx2any''. ! SEE ALSO ''stx2any'' (1) ! AUTHOR This page is written by w_author. stx2any/examples/artikkeli.txt0000644000175000017500000003436610423671243020500 0ustar pkalliokpkalliok00000000000000w_title(Strukturoitu teksti -- mitä vitun väliä on dokumenttimuodoilla?)dnl w_author(Panu A. Kalliokoski)dnl w_date($ $Date: 2004/02/12 16:57:59 $ $)dnl w_language(finnish)dnl ! Johdanto Jokainen meistä on varmasti törmännyt joskus hämmentävään ongelmaan: pitää kirjoittaa lappu, muistio, tiedote, pöytäkirja, muistiinpanoja, artikkeli, tai jotain muuta tietokoneella. Suurin osa ihmisistä kummempia ajattelematta avaa tekstinkäsittelyohjelman ("Millä muulla niitä sitten voi kirjoittaa?") tai jotkut PIM:n (/personal information manager/, eli siis henkilökohtainen tiedonhallintaohjelma). Tämä on "ihan hyvä" lähestymistapa, mutta jokainen, joka on joskus yrittänyt siirtää kaikki vanhat dokumenttinsa uuteen ympäristöön (uudelle koneelle, uuteen käyttöjärjestelmään tai edes vain uudelle versiolle tekstinkäsittelyohjelmaa), tietää, mikä tuska tästä voi seurata. Tässä artikkelissa on tarkoitus kartoittaa vaihtoehtoja periaatteessa yksinkertaisen ongelman ratkaisuun: millä ja mihin tiedostomuotoon kirjoitan satunnaiset lappuseni? ! Lähtökohta: WYSIWYG-dokumentit WYSIWYG[[ "What You See Is What You Get" ]] on yhteinen nimitys sille paradigmalle, jossa esitetään dokumentti näytöllä samassa muodossa, kuin miltä se oletettavasti näyttää "lopputuloksessa". Lopputuloksena voidaan pitää paperitulostetta, ''www''-sivua, tai sitä, mitä kaverin koneessa pomppaa näytölle, kun hän avaa dokumentin. WYSIWYG-ohjelmiksi kutsutaan ohjelmia, joissa dokumentteja työstetään tällä tavoin. Joihinkin ongelmiin WYSIWYG-ohjelmat ovat lähes ainoa järkevä ratkaisu: näitä ovat esimerkiksi lentolehtisten tai mainosten suunnittelu, jossa on paljon graafista sisältöä ja visuaalisten elementtien asettelu on tarkkaa. Mutta tähän WYSIWYG-ohjelmien "hyvä käyttö" suunnilleen jääkin. WYSIWYG-dokumenttien on todettu vääristävän ihmisten ajattelua tavattoman monella tavalla: # ne käyttävät tyypillisesti tiedostomuotoja, jotka vaihtelevat vähän väliä (tyypillisesti aina, kun päivittää tekstinkäsittelyohjelman, se käyttää jo uutta tiedostomuotoa), aiheuttavat mystisiä yhteensopimattomuusongelmia ja pakottavat organisaatiot valitsemaan yhden WYSIWYG-työkalun monien joukosta, jottei organisaation sisäisessä viestinnässä jouduttaisi koko ajan tappelemaan muunnosten (/konversioiden/) kanssa; # ne luovat ihmisille illuusion siitä, että WYSIWYG-dokumentti voi sisältää tarpeeksi tietoa näytettäväksi missä tahansa ympäristössä. Tämä tuottaa ongelmia esimerkiksi ''www''-sivujen tuottotyökalujen kanssa, kun sivujen tuottajat eivät käsitä, että lukijoilla voi olla eri selain, erikokoinen näyttö, erilaiset väriasetukset, erilainen kirjasinvalikoima, tai voidaanpa sivuja lukea jollain täysin epävisuaalisellakin, esim. puhesynteesiselaimella; # ne pakottavat ihmiset tekemään vähän väliä muotoiluja (lihavointeja, kursivointeja, kirjasinkoon muutoksia) tekstiin, jos sille haluaa jotain rakennetta. Tämä häiritsee ihmisten keskittymistä tekstin sisältöön, varsinaiseen asiaan. Lisäksi tämä estää tuottamasta dokumentista muotoilultaan erilaisia versioita, koska dokumentissa ei ole riittävästi tietoa esimerkiksi sen koneelliseen arvaamiseen, mikä on otsikko, jos otsikkojen ulkonäköä päättää joskus muuttaa; # ne houkuttelevat ihmisiä pelleilemään dokumentin ulkonäöllä: tekemään dokumentteja, jotka "luovasti" poikkeavat perinteistä tekstin asettelun, muotoilun ja järjestelyn suhteen. Näistä kaikista syistä pitäisi olla ilmeistä, ettei _mitään_ satunnaisia tekstejä tai muistioita pidä koskaan kirjoittaa WYSIWYG-työkaluilla. Tämä on tärkeää sekä oman että lähimmäistenne mielenterveyden ja -selkeyden takia. ! Raakateksti Yleensä ensimmäinen reaktio kaikkeen tähän on mennä suoraan raakatekstin käyttöön tai keskitason semanttisiin merkintäkieliin[[ Näistä puhutaan seuraavassa osiossa enemmän. ]]. Varsinkin laitoksella, missä on vahvat ''emacs''-perinteet, on paljon ihmisiä, jotka ymmärtävät raakatekstin olemuksen ja kauneuden -- mutta löytyy niitäkin, jotka käyttävät mieluummin Windowsin Notepadia kuin Wordia. "Raakateksti", niille, jotka eivät sitä tunne, on tiedostomuoto, jossa jokainen dokumentti on jono merkkejä. Muotoiluja on sen verran, että tietty merkki tarkoittaa rivinvaihtoa (siis uuden rivin aloitusta) tekstissä ja lisäksi on toinen merkki, jolla voi merkitä sarkainvaihtoja (tämä ''tab''-merkki toimii yleensä kuten kirjoituskoneiden ''tab'', eli kohdentaa tekstin jatkumaan seuraavasta 8:lla jaollisesta merkkisarakkeesta). Paljon muuta ei sitten olekaan. Ei lihavointeja, ei kappalevaihtoja (muuta kuin kaksi peräkkäistä rivinvaihtoa), ei kirjasimen vaihdoksia, ei alaviitteitä eikä mitään muutakaan. Raakateksti on tiedostomuotona pysynyt jotakuinkin muuttumattomana 70-luvulta lähtien. Raakateksti on itse asiassa erittäin hyvä muoto kaikenlaiselle kirjoitukselle. Esimerkiksi sähköpostin pitkä perinne raakatekstimuotoisena[[ ennen kuin HTML-muotoista sähköpostia alkoi tunkea joka paikasta. ]] osoittaa, että "mitä raakatekstillä ei voi tehdä, sitä ei tarvita". Vuosien aikana on kehittynyt tavaton määrä käytäntöjä, miten erilaisia asioita voi ilmaista raakatekstissä: korostus `*'tähdillä`*' sanan ympärillä, listat ranskalaisilla viivoilla, ja niin edelleen. Joitain ongelmia raakatekstissä kuitenkin on. Mitä, jos haluan tulostaa dokumenttini, ja _haluan_ sinne korostuksia? Mitä, jos muistiinpanoistani kasvaa artikkeli: eikö olisi kannattanut kirjoittaa se julkaisukelpoiseen muotoon alusta lähtien? Mitä, jos haluaisin raakatekstistäni ''www''-sivun? Näihin ongelmiin yksi vastaus on seuraavassa osiossa. ! Keskitason semanttiset merkintäkielet Keskitason semanttisilla merkintäkielillä tarkoitetaan tiedostomuotoja, johon on jollain standardilla tavalla merkitty eri tekstiosioiden typografinen merkitys: esimerkiksi "tässä on kappale, tuossa on lista, tämä on otsikko, tuo on huomautus". Yleensä nämä merkinnät tekstiosioiden merkityksistä ovat tekstin joukossa, mistä tuleekin nimitys "merkintäkieli" (/markup language/). Esimerkkejä keskitason semanttisista merkintäkielistä ovat HTML, XHTML, LaTeX, ms-makrot, DocBook jne. Myös jotkin WYSIWYG-ohjelmat[[ esimerkiksi MS Word ja Openoffice.org ]] antavat mahdollisuuden keskitason semanttisiin muotoiluihin; toinen asia on, älyävätkö käyttäjät käyttää näitä mahdollisuuksia. Esimerkiksi HTML on itse asiassa aika hyvä muoto kirjoittaa dokumenttinsa suoraan. HTML:n tuottoon ei saa käyttää WYSIWYG-työkaluja, koska silloin ei voi tietää, mitä varsinaiseen tiedostoon merkitään tai vastaako se ollenkaan tekstin todellista rakennetta. LaTeX on erinomainen merkintäkieli, jos aikoo tehdä vakavasti otettavia tieteellisiä julkaisuja. Molemmissa on itse asiassa aika matala oppimiskynnys (varsinkin, jos on tottunut käsittelemään raakatekstiä), ja molempia on melko miellyttävää lukea sellaisinaan (siis raakatekstinä). Ongelmiakin on. Vaikka oppimiskynnys on matalahko, se on kuitenkin olemassa, eikä kaikilla ole aikaa vaivata päätään tällaisella. Lisäksi merkinnöissä voi tehdä virheitä, jolloin dokumentti saattaa näyttää väärältä prosessoidessa tai dokumentin prosessointijärjestelmä (esim. ''latex''-komento) kieltäytyy kokonaan dokumentin käsittelemisestä ja jättää käyttäjän metsästämään paikkaa, jossa virhe piilee. HTML on myös sikäli ongelmallinen merkintäkieli, että sen laajentaminen omilla merkinnöillä (jos joskus sattuisi moisia tarvitsemaan) ei ole mahdollista, sillä HTML on laaja ja hitaasti kehittyvä standardi. Lisäksi näiden tiedostomuotojen muuntaminen toisikseen tai paperille tulostetuiksi dokumenteiksi (ylipäänsä mihinkään, mikä ei ole niiden primäärinen media) jättää joskus toivomisen varaa lopputuloksen tyylikkyydessä ja huolitelluudessa. ! Korkean tason semanttiset merkintäkielet On ehkä myös syytä sanoa sananen korkean tason semanttisista merkintäkielistä. Nämä ovat kieliä, joissa on merkitty, mitä dokumentissa oleva teksti oikeasti _tarkoittaa_ tai _on_. Esimerkiksi, sen sijaan että merkinnöissä sanottaisiin, että tässä on lista ja listassa on tällaiset kohdat, sanotaankin, että tässä on osanottajalista ja listassa on tällaisia nimiä ja tällaisia yhteisöjä. Esimerkkejä korkean tason semanttisista merkintäkielistä ovat erilaiset XML- ja SGML-sovellukset, erilaiset verkkoprotokollat, jne. Myös tietokantojen voi katsoa sisältävän korkean tason semanttista /metatietoa/ [[ tarkoittaa tietoa tiedosta: siis tietoa siitä, mitä jokin toinen tieto on. ]], vaikkeivät ne merkintäkieliä olekaan. Nämä kielet ovat usein kohdealueen mukaan erikoistuneita, eli suunnilleen jokaiselle tilanteelle elämässä (tai maailmassa) pitää olla oma merkintäkielensä, jolla voidaan merkitä tietoja kyseisestä todellisuuden alueesta. Dokumentit sisältävät yleensä riittävästi tietoa vaikka mihin muunnoksiin ja niistä pystyy tuottamaan kaikenlaisia yhteenvetoja ja muuta, mutta tällainen prosessointi edellyttää ohjelmointityötä ja jo pelkkä merkintäkielen määrittely muistuttaa deklaratiivista ohjelmointia. Suurimpaan osaan normaalielämän tarpeista nämä kielet ovat aivan ylimitoitettuja, ja niiden käyttämisen oppimiskynnys on varsin korkea. ! Strukturoitu teksti, vihdoin ja viimein Strukturoitu teksti on yritys liittää raakatekstin pitkä perinne keskitason semanttisten merkintäkielten hyviin puoliin. Raakatekstin suurimpia rasitteitahan on huono muunnettavuus muihin muotoihin: tiedostomuotoihin tai vaikkapa tyylikkääksi tulosteeksi. Strukturoitu teksti, lyhyesti sanottuna, on raakatekstiä, jossa noudatetaan tiukasti tiettyjä käytäntöjä erilaisten keskitason semanttisten muotoilujen merkitsemisessä. Enimmäkseen nämä merkintätavat tulevat raakatekstin perinteistä; kuitenkin siellä, missä perinteiset muotoilut ovat monitulkintaisia, edellytetään selkeää merkintää siitä, tarkoitetaanko muotoilulla sitä vai tätä. Esimerkkejä muotoiluista, jotka noudattavat täsmälleen sähköpostiperinteitä, ovat `*'tähdillä`*' tehdyt korostukset, kahdella rivinvaihdolla merkityt kappalevaihdot, listat ranskalaisilla viivoilla ja niin edelleen. Esimerkkejä rakenteista, joita on täytynyt yksiselitteistää, ovat: otsikot:: vanhastaan merkitty panemalla otsikko omalle rivilleen, jota edeltää ja seuraa tyhjä rivi. Seuraava rivi on saattanut sisältää viivoja ikään kuin "alleviivaukseksi" otsikolle. Strukturoidussa tekstissä otsikko merkitään aloittamalla rivi huutomerkillä. termi-määrittelylistat (kuten tämä tässä):: vanhastaan merkitty sisentämällä määrittelyt. Ei sisällä riittävästi tietoa termin varmaan tunnistamiseen: strukturoidussa tekstissä termi pitää panna omalle linjalleen ja lopettaa linja kahteen kaksoispisteeseen (''::''). pakotetut rivinvaihdot:: vanhastaan merkitty lisäämällä rivinvaihto. Ei erotettavissa automaattisesti tuotetusta rivinvaihdosta (esim. sähköpostissa rivin vakiopituus on enintään 72 merkkiä, minkä jälkeen viimeistään pitäisi tulla rivinvaihto); strukturoidussa tekstissä merkittävä rivin lopussa kahdella kauttaviivalla (''//''). Strukturoitu teksti ei olisi paljon mitään ilman toteutusta, jolla siitä voi tuottaa toisia tiedostomuotoja. Tällainen toteutus on sattumoisin olemassa, kirjoittaja on sattumoisin sen tekijä, ja koska kirjoittaja on myös yleisen kielitieteen ATK-ylläpitäjä, kyseinen ohjelma on sattumoisin asennettuna laitoksen ''venus''-palvelimelle. Ohjelman nimi on ''stx2any'' ja siitä saa lisää tietoa komennolla ''man stx2any''. Nämä ovat tavoitteet, jotka mielessä ''stx2any'' on kirjoitettu: - Lähdemuodon (strukturoidun tekstin) tulee olla vaivatonta oppia, tiivistä ja kaunista luettavaa sellaisenaan (siis raakatekstinä). - Säännöstön pitää olla varsin voimakas, eli strukturoituna tekstinä pitää voida esittää paljon ja monimutkaisia asioita. - Lähdemuodon pitää olla laajennettavissa sekä siten, että siihen voi lisätä omia merkintöjä, että siten, että sen sekaan voi kirjoittaa suoraan kohdemuodon (HTML tms.) merkintöjä. - Strukturoidusta tekstistä tuotettujen kohdemuotoisten dokumenttien tulee olla tyylikkäitä, kohdemuodolle ominaisia (esim. HTML-tulosteen pitää näyttää ''www''-sivulta eikä paperidokumentin ''www''-versiolta), ja säilyttää suunnilleen alkuperäisen dokumentin ulkonäkö. - Kohdemuotoisen dokumentin tulee olla kohtalaisen siisti myös sisäisesti, eli konversion tulokseen ei saa päätyä hirveää määrää kummallista moskaa (fonttimäärityksiä tms.). Lisäksi tuloksen tulee sisältää sen verran alkuperäisen dokumentin asettelusta kuin mahdollista, jotta sitä on miellyttävää lukea myös sellaisenaan (raakatekstinä). Tällä hetkellä ''stx2any'' osaa muuntaa strukturoitua tekstiä HTML-, man- ja LaTeX-muotoon. Uusia tulosmuotoja saatetaan lisätä tulevaisuudessa, mutta saatetaan olla lisäämättäkin, sillä näistä kolmesta muodosta dokumentin voi edelleen muuntaa lähes miksi tahansa maan ja taivaan välillä. Tämä artikkeli on kirjoitettu strukturoituna tekstinä. w_link(mailto:pkalliok@ling.helsinki.fi, Panu Kalliokoski) ---- ! Appendix: millä sitä raakatekstiä sitten kirjoitetaan? Jokaiseen ympäristöön on olemassa joitain ohjelmia, jotka osaavat käsitellä puhdasta raakatekstiä, ja jokaisessa ympäristössä on ainakin jokin sellainen valmiina. Niitä kutsutaan /editoreiksi/. Joissain ympäristöissä on valmiiksi erittäin hyviä editoreita, joissain taas joutuu näkemään vaivaa hommatakseen kunnollisen. Kirjoittajan kokemus on ensisijaisesti ''Linux''-ympäristöstä, joten tietämys muiden ympäristöjen editoreista on hatarahkoa. Linux:: Hyviä editoreita ovat esim. ''emacs'' ja ''vim'', joista jälkemmäisellä on hyvin korkea oppimiskynnys. Muita hyviä editoreita ovat ''joe'' ja ''jed''. Kohtalaisia editoreita ovat ''pico'', ''nano'' ja ''uemacs'' (eli "mikroemacs"). Useimmiten näistä on monia valmiiksi asennettuina. Windows:: Välttävä editori on Windowsin NotePad. WordPad ei tuota kunnon raakatekstiä. Parempiakin editoreita on saatavilla, esim. EditPad, mutta kirjoittaja ei tiedä näistä tarpeeksi. Macintosh:: Ainakin jossain vaiheessa jokaisen macin mukana tuli AppleScript joku-joku, joka oli varsin hyvä editori. Myös järjestelmän Teksturi II tuottaa hyvää raakatekstiä, vaikka onkin orientoitunut jonkin verran WYSIWYG-suuntaan. Teksturia ei pidä käyttää, sillä on vakavia kokorajoituksia dokumenteille. Hyviä editoreita on ainakin BBEdit (Lite) ja muistaakseni Alpha-niminen editori. KDE:: Kohtalainen editori on KEdit ja kunnollinen Kate. Tietysti voi myös käyttää alla olevan järjestelmän editoreita. Tämä artikkeli on kirjoitettu ''vim'':lla ''Linux''-ympäristössä. stx2any/examples/Stx-ref.txt0000644000175000017500000010276410471044066020047 0ustar pkalliokpkalliok00000000000000w_title(Stx markup reference)dnl w_author(Panu Kalliokoski)dnl define(w_tag, ``'w_lt`'$1`'w_gt`'')dnl define(w_bracket, `w_tag($1)$2`'w_tag(/$1)')dnl define(w_macro, `w_literal(``$1'')')dnl ! Preliminary note Please note that reading this document is _not_ the proper way to learn Stx. You should never spend time learning tools you don't have to learn. Just start to write Stx (probably with the help of w_crosslink(Stx-doc.html)), and check this document if/when the need to do something complicated arises. This document is arranged roughly by how frequently the material is of use for people. More frequently useful things come first, less frequently useful come after. ! Command line options These are documented on w_crosslink(s2aman, the manual page of ''stx2any''). ! Formatting markup !! Markup with abbreviations !!! Structural markup empty line:: w_macro(w`_'paragraph):: causes a paragraph break w_literal(`/')text`'w_literal(`/'), w_literal(`_')text`'w_literal(`_'):: w_macro(w`_'techemph)(text), w_macro(w`_'emph)(text):: normal emphasis. Slashes (''/'') produce "technical" emphasis, underscores (''_'') "semantic" emphasis. w_literal(`*')text`'w_literal(`*'):: w_macro(w`_'strong)(text):: strong emphasis w_literal(`w_apo`'w_apo')text`'w_literal(`w_apo`'w_apo'):: w_macro(w`_'literal)(text):: literal formatting (short excerpts of text copied from somewhere, some program names, commands, abbreviations, etc.) w_literal([[` ')text`'w_literal(` ']]), w_literal([[`-')text`'w_literal(`-']]):: w_macro(w`_'footnote)(text):: footnotes ''//'' (at the end of line):: w_macro(w`_'linebr):: hard linebreaks ''--'', ''---'', ''----'', ... (alone on a line):: w_macro(w`_'sectbreak)(/number/):: a section break ("transition"). The /number/ (of dashes) determines the "strength" of the section break. ''{{{'', ''}}}'' (alone on a line):: begin and end a preformatted block, respectively ''!'', ''!!'', ''!!!'', ... (at the beginning of a line):: w_macro(w`_'headl)(/number/, text):: causes the line to be made into a heading. The /number/ (of exclamation points) determines the level of the heading. ''*'', ''-'' (at the beginning of a line, with optional indentation):: a list item ''#'' (at the beginning of a line, with optional indentation):: a numbered list item ''::'' (at the end of a line, line optionally indented):: makes the line a definition term. The corresponding definition follows on the next lines, indented. More indentation causes lists to become nested. If a paragraph is indented without being on the top level of a list item, it is made into a citation block. !!! Special characters w_literal(`"')text`'w_literal(`"'):: w_macro(w`_'quotation)(text):: quotation marks item`'w_literal(`--')item, text w_literal(`--') text:: w_macro(w`_'endash), w_macro(w`_'emdash):: en dashes and em dashes text`'w_literal(`...'):: w_macro(w`_'ellipsis):: ellipsis (a pause or omission marker) text w_literal(`-w_gt') text, text w_literal(`w_lt-') text:: w_macro(w`_'rarrow), w_macro(w`_'larrow):: right and left pointing arrows w_literal(`(c)') text:: w_macro(w`_'copyrightsign):: a copyright sign w_literal(`('tm`)'):: w_macro(w`_'trademarksign):: a trademark sign !!! Other markup with abbreviations w_autorefer(Link abbreviations) are discussed in a separate section. At the beginning of file (before the first empty line in the document), you can give document metadata by writing lines of the form ''metadata_type: value''. For example, put the following lines at the beginning of a file: {{{ title: Very important document author: me language: english }}} All metadata is available for setting in this way. Different kinds of metadata are given in the section w_autorefer(Macros for document metadata). You just leave the ''w_'' prefix away. !! Link abbreviations You can use /link abbreviations/ if you request them separately.[[-''stx2any'' has a command line switch to activate link abbreviations.-]] If you enable them, almost all brackets become special. All link abbreviations are one-line syntaxes, that is, you have to take care that they don't get wrapped over two lines, or they won't be recognised as link abbreviations. There are also indirect link references, which are gathered in separate /link data blocks/. Link data blocks do not affect the rendering of your document in any way except by providing information for linking. You can group them e.g. at the beginning of your document, at the end, or after every paragraph (which I think looks the neatest). w_literal(`[+')some text`'w_literal(`+]'):: This makes a label. The text /some text/ is inserted at this point, and the label can be later referenced by the name /some text/. When link abbreviations are enabled, headings also produce labels automatically. w_literal(`http://')nice-to-meet-you/blah/blah:: URL's are marked as URL's without any special syntax. Recognised URL schemes are ''http'', ''https'', ''ftp'', ''ftps'', ''gopher'', ''file'', ''nntp'', ''mailto'' and ''news''. text`'w_literal(`[')link-id`'w_literal(`]'):: w_literal(`[')text`'w_literal(`][')link-id`'w_literal(`]'):: Produces a link to /link-id/ with /text/. In the first form, /text/ cannot contain spaces, whereas in the second form it can. The interpretation of /link-id/ is explained below. w_literal(`[')link-id`'w_literal(`]'):: Produces a "nameless link" to /link-id/. The text for the link is the label text for labels, the foreign document title (or filename) for cross links, the URL itself for URL's, and an empty string for the alternative text of inline images. w_literal(`[')link-id`'w_literal(`]') /another link-id/:: put in separate paragraphs ("link data blocks"), lines like these make /indirect link references/, declaring /link-id/ to be equal to /another link-id/. For every /link-id/, different interpretations are tried in order until an appropriate one is found. This is the order: # if it is an indirect link reference, it is rewritten and the new link id is tried; # the link is made a cross reference, if there is a label corresponding to the link id; # the link is made a cross link (between documents), if there is a document with corresponding document id or file name; # if the link id begins with ''img:'', the link is made into an inline image to the file given by the rest of the link id (+ a suffix; see the documentation of w_macro(`w_img')). # the link is made into an ordinary link if the link id looks like an URL. # if all else fails, the link id just becomes footnote text at the point where the "link" was. !! Macro-based markup All Stx macros begin with a prefix ''w_''. Normal ''m4'' macros are also available, with the exception of GNU m4 ''format'', which is too common a word to be left as a macro. w_macro(`w_beg')(/env/ [, /env args/]), w_macro(`w_end')(/env/):: begin and end the environment /env/, respectively. A list of available environments is in the next section. Some environments take arguments (/env args/ above); these are described with the environments. w_macro(`w_use')(/package-or-file/), w_macro(`include')(/file/):: use the definitions in /package/ in the document, or, include the contents of /file/ in the input. These two are almost the same thing, but w_macro(`w_use') makes sure that the file is only included once, and adds the suffix ''.m4'' to its name. Use w_macro(`w_use') when in doubt. The included file is not subject to Stx abbreviations, but goes through ''m4'' processing. These are a good way for adding templates to your HTML pages (just dump some HTML markup into the diversions ''frontmatter'' and ''backmatter''), sharing some content between documents, or inserting long sections of content where abbreviation processing is not to take place. If you want to concatenate many Stx documents, it's better to give them all as arguments to ''stx2any'' -- that way they go through abbreviation processing. w_macro(`w_man_desc')([/name/,] /short description/):: This helper macro is for writing properly formatted "NAME" sections for man. The calls should be at the beginning of your man page, one by a line. /name/ defaults to w_macro(`w_title'), and on most pages, you need only one w_macro(`w_man_desc'). !!! Macros for document metadata w_macro(`w_title')(/text/):: w_macro(`w_title'):: w_macro(`w_gettitle'):: set or get the title of the document. If the argument /text/ is present, the title of the document is set to /text/; if it is absent, the macro expands to the (previously set) title. w_macro(`w_gettitle') is the old name for w_macro(`w_title') without arguments. w_macro(`w_doc_id')(/text/):: set the unique id of the document. This can be used to refer to the document; currently w_macro(`w_crosslink') supports it. w_macro(`w_char_coding')(/charset/ [, /long-charset-name/]):: declare the input text to be in character coding /charset/. Supported values are (currently) ''ascii'', ''latin1'', ''latin9'' and ''utf8''. The default is ''latin1''. The man output format is unable to carry this piece of metadata. The optional parameter /long-charset-name/ can be used to make documents in character sets that are not natively supported. The /charset/ is used for LaTeX (and possibly internally); /long-charset-name/ is used for HTML and DocBook. w_macro(`w_author')(/text/):: w_macro(`w_author'):: set or get the author of the document. w_macro(`w_date')(/text/):: w_macro(`w_date'):: w_macro(`w_getdate'):: set or get the date of modifying / releasing the document. w_macro(`w_getdate') is the old name for w_macro(`w_date') without arguments. Note that Stx provides no magic for managing modification dates; it is up to you to keep the date correct, fetch it automatically from the file system, or to use e.g. features provided by version control systems to manage it. The meaning of the "date" of a document is a somewhat ambiguous; as a consequence, Stx doesn't try to guess what _you_ use it for. w_macro(`w_section')(/number/):: for man pages, set the section into which the man page belongs w_macro(`w_language')(/language/ [, /langcode/]):: set the primary language the document is written in. /language/ is the LaTeX-style, full language name (all lowercase); /langcode/ is the ISO-style, two-letter language code, and defaults to the two first letters of /language/. (Hey, I had to come up with something!) w_macro(`w_documentclass')(/class/):: w_macro(`w_documentclass'):: (LaTeX only) set or get the document class of the document. (Default: ''article'') w_macro(`w_slideheader')(/text/):: w_macro(`w_slidefooter')(/text/):: Set the header and footer text, respectively, for slides, if you use the slide environment. !!! Macros for links and references These macros have shorthands in w_autorefer(Link abbreviations). w_macro(`w_img')(/basename/, /text/):: put in markup for including an inline image in the document. The name of the image is given by appending a dot (.) and a suffix to the given /basename/. This allows you to automatically produce the pictures for different formats: no picture format works for every output format. The suffix is given by a command line option; see w_crosslink(s2aman, the manual page of ''stx2any''). The base of a relative filename can be altered by defining w_macro(`w_base'). The /text/ in the second parameter is always displayed alternatively, never in addition to, the image. w_macro(`w_link')(/url/, /text/):: produce a link to /url/ w_macro(`w_url')(/url/):: put /url/ into the document. In HTML, it also becomes a link. w_macro(`w_crosslink')(/doc-id/ [, /text/]):: produce a cross-link from this file to the other document. /doc-id/ is the target document's unique id (as set by w_macro(`w_doc_id') in that document) or, failing that, its filename. The link text will be the destination document's title, as gathered by w_crosslink(gstman, ''gather_stx_titles'') or, if it has no title, its filename. The base of the relative link can be altered by defining w_macro(`w_base'); use it if your documents are in different directories. If the second argument is present, its /text/ will be used as the link text instead of the destination document's title / filename. w_macro(`w_label')(/label/, /text/):: produce a label (a place that can be referenced later) w_macro(`w_refer')(/label/, /text/):: produce a cross reference to the label /label/ w_macro(`w_autolabel')(/text/):: w_macro(`w_autorefer')(/text/, /link text/):: The same as w_macro(`w_label') and w_macro(`w_refer'), except that the label is automatically generated from /text/. If /link text/ is not present, /text/ is used for the link text. w_macro(`w_index')(/div/, [ /marker/, ] /text/):: put the given /text/ into diversion /div/ (the "index") as well as at the current point in document. The current point is cross referenced from the index. This command is useful for creating lists-of-tables and such stuff, but is not very well thought out yet. The text of /marker/, if given, is put into the index but not made part of the link. w_macro(`w_indexword')(/div/, /word/):: make the word /word/ so that it will always produce an index entry in /div/ when it occurs in the text !!! Diversions w_macro(`w_begdiv')(/div/), w_macro(`w_enddiv')(/div/):: begin and end outputting text into diversion /div/, respectively. Diversions can be used for rearranging input. The following diversions are currently used: ''body'':: Body text. This is the default diversion: all text initially goes into the body. ''ingr'':: Ingress. This diversion is placed immediately under the document title. ''frontmatter'':: placed before any other content in the document. Can be used e.g. for making document templates. ''backmatter'':: placed after any other content in the document. ''metas'':: placed in the header of HTML documents. You need this if you want to e.g. include a stylesheet in your document. ''preamble'':: placed in the preamble of LaTeX documents. This is a good place for your own LaTeX declarations, importing packages, etc. ''defs'':: this is the trashcan diversion. It is useful for including stx-level comments, making macro definitions without producing extra whitespace in the output, and other things like that. ''footnote'':: this diversion is used internally for gathering footnotes in output formats that don't natively support them. w_macro(`w_dumpdiv')(/div/):: place text gathered thus far in diversion /div/ at this spot. !!! Whitespace w_macro(`dnl'):: Eats everything up to and including following newline. Good for placing comments in the document and deleting spurious newlines from the output. w_macro(`w_nl'):: Causes a newline in the output. !! Environments Environments must be properly nested, i.e. w_macro(`w_beg')(/foo/) must be closed by w_macro(`w_end')(/foo/). Moreover, these abbreviated constructs are internally environments and must therefore be properly nested with explicit environments: * lists (unnumbered, numbered, and term-definition) * definitions of term-definition lists * citation blocks * preformatted blocks * footnotes * table rows and cells ''abstract'':: the abstract of the document. This text is placed in the diversion ''ingr''. ''admonition'':: Admonitions are short notes that should stand out from the rest of the text. They are usually one or a few paragraphs long. The environment takes a parameter, the admonition "type"; for example, w_macro(`w_beg')(''admonition'', Note). Special admonition types supported by DocBook XML are "Note", "Tip", "Warning", "Caution", and "Important". ''center'':: the text in the environment becomes centered. ''citation'':: This is similar to an ordinary citation block (which is indicated by mere indentation), but has an attribution (who said the quoted stuff) given as a parameter, e.g. w_macro(`w_beg')(''citation'', Chuck Moore). ''comment'':: The text in the environment becomes commented in the output, i.e. it becomes a comment in whatever language the output language is. This environment can be used in the middle of a line. ''compactlist'':: This environment makes a list without indents or list markers. Every line becomes one item in the list. The reason this type of list has such a long name is that it should not be used except in special cases: most output formats do not have semantic markup for this kind of list, and a list that does not have the ordinary look of a list is somewhat confusing. The environment is mostly useful for building navigation menus etc. where space is a scarce resource and putting list markup in is null-semantic. ''float'':: Floats are blocks of text or other content that are separated from the normal flow of body text. They are used for lengthy tables, figures and pictures, and notes that relate generally to the subject at hand. This environment makes the enclosed text a float. The environment takes two parameters, as in: w_macro(`w_beg')(''float'', /pos/, /caption/). The first parameter /pos/ determines the placement of the float and is composed of one-character placement hints, in order of preference of the placement of the float. (First character tells the most preferred placement and so on.) Some placements may not be available in some formats. The meanings of the characters are as follows: ''h'':: place the float here, in the running text. ''n'':: place the float "near", for example after the paragraph or on the same page. ''f'':: place the float "far". It may be e.g. several pages away. ''m'':: place the float in the margin. This is a way to make margin notes. The second parameter, /caption/, tells the caption text of the float, if any. ''ifeq'':: The text in the environment is only inserted if the (two) environment parameters match. This environment can be used in the middle of a line. For example, the following only puts the included text in when producing a LaTeX document: w_macro(`w_beg')(''ifeq'', w_macro(`w_outputfmt'), latex) text... w_macro(`w_end')(''ifeq'') ''slide'':: To make slides, divide the text into slide environments following each other. You can set the slide header and footer with w_macro(`w_slideheader') and w_macro(`w_slidefooter'). For LaTeX, the slide show is implemented with the ''seminar'' document class. For HTML, the result is a S5 slide show, about which you can read more at w_url(http://www.meyerweb.com/eric/tools/s5/). You need to fetch the style sheets and javascript file yourself. You can define w_macro(`w_s5url') to specify the directory where S5 files reside (default is ''ui/default/''). For man and DocBook XML, the slides simply suck. ''table'':: The text in the environment is a table with columns separated by ''||'' and rows closed by ''//'' at the end of a line. Column types are given as parameters to the table environment, as in: w_macro(`w_beg')(''table'', r, p). The meanings of column types are as follows: ''l'':: produce a left-aligned column. ''r'':: produce a right-aligned column. ''c'':: produce a centered column. ''p'':: produce a column where text may be put on multiple lines. ! Extension markup All macros beginning with a ''w_'' (or ''@w_'') prefix are reserved for ''stx2any''. You can redefine them, of course, if you want to change the operation of ''stx2any''. For your own macros, you can choose your own prefix or use macros without a prefix at all. Environments, diversions and counters have their own namespaces under ''@w_'', and you should not worry about them. !! Definitions w_macro(`define')(``macro'', ``expansion''):: define your own macro. Further occurrences of /macro/ will be replaced by the /expansion/. w_macro(`w_def_in_fmt')(/format/, ``macro'', ``expansion''):: define a macro, but only for output format /format/. In addition to making output format specific macros, you can use this to add some neatness that can be expressed only in some output formats to a word: for example, w_macro(`w_def_in_fmt')(docbook-xml, Dr, w_bracket(Honorific, ````Dr'''')) w_macro(`w_define_env')(/environment/, ``beginstuff'', ``endstuff''):: define a new /environment/. /beginstuff/ will be executed at the beginning of the environment, and /endstuff/ will be executed at the end. Formal parameters (''$1'' etc) will give the environment parameters in both /beginstuff/ and /endstuff/. w_macro(`w_derive_env')(/env/, /base-env/, /num/, ``pre-begin'', ``post-begin'', ``pre-end'', ``post-end''):: this command is *deprecated*. It will continue to work, but there is no need for it. w_macro(`w_define_div')(/diversion/):: declare a new /diversion/ for gathering text. After declaration, you can use w_macro(`w_begdiv'), w_macro(`w_enddiv') and w_macro(`w_dumpdiv') on that diversion. w_macro(`w_outputfmt'):: this macro has expansion ''html'', ''man'', ''docbook-xml'' or ''latex'' depending on which output format we're converting to. You can use it for writing your own format-aware macros. !! Counters w_macro(`w_newcounter')(/counter/ [, /refcounter/]):: w_macro(`w_setcounter')(/counter/, /value/):: w_macro(`w_delcounter')(/counter/):: create, set the value of, or delete /counter/, respectively. If a counter has a /refcounter/ (as specified in w_macro(`w_newcounter')), the /refcounter/ is reset every time the counter changes value. Calls to w_macro(`w_newcounter') and w_macro(`w_delcounter') can be nested for a counter. w_macro(`w_newcounter') resets the counter to zero and w_macro(`w_delcounter') returns the counter to the value it had before w_macro(`w_newcounter'). w_macro(`w_stepcounter')(/counter/ [, /step/]):: Increment the value of /counter/ by /step/. If the /step/ argument is not present, the counter is incremented by 1. w_macro(`w_counter_arabic')(/counter/):: w_macro(`w_counter_alpha')(/counter/):: w_macro(`w_counter_Alpha')(/counter/):: give the value of /counter/ as arabic number, lowercase letter, or uppercase letter, respectively. !! Hooks w_macro(`pushdef')(``macro'', ``expansion''):: w_macro(`popdef')(``macro''):: temporarily change the definition of a macro. w_macro(`pushdef') gives the macro a new definition, w_macro(`popdef') sets it back to the old one. w_macro(`define') always changes the most recent definition, never the earlier ones. w_macro(`w_push_env')(/environment/):: w_macro(`w_pop_env')(/environment/):: temporarily change the definition of /environment/. (This is not for the faint of heart.) w_macro(`w_push_env') changes the environment to a null environment that does nothing; after that, you can change the definition with w_macro(`w_define_env') or w_macro(`w_derive_env'). w_macro(`w_pop_env') reinstates the old definition. The following macros are good candidates for temporary redefinition. w_macro(`w_softbr'):: called at the beginning of an ordinary text line. w_macro(`w_eline'):: called at the end of a text line. w_macro(`w_softpara'):: called at empty lines. w_macro(`w_linebr'):: called for hard linebreaks (//), at the end of a line but before w_macro(`w_eline'). w_macro(`w_paragraph'):: called at the beginning of a paragraph block. w_macro(`w_horizbr'):: called at the horizontal separator (||). w_macro(`w_indent_hook'):: called after an increased indent. w_macro(`w_dedent_hook'):: called before a decreased indent. The following environments are "good" candidates for temporary redefinition. ''text'':: ordinary text. ''q'':: citation blocks. ''footnote'':: footnotes. ''litblock'':: literal blocks. ! Quoting Warning: don't read this section unless you really need to or you want your head to explode. You have been warned. "Quoting" means the act of making literal text from something that would have been considered markup ordinarily. For instance, if you need a word surrounded by `*'asterisks`*' not to be converted to strong emphasis, you need some kind of quoting. Simple rule of quoting: don't quote unless you have to. ''stx2any'' has been built so that most of the time it gets the writer's intention correct. When it doesn't, you might have to resort to quoting. ''stx2any'' has four types of quoting: # ''m4'' quoting # abbreviation quoting # quote quoting # destination format quoting (not actually the job of ''stx2any'') The reason for having so many is partly the implementation of ''stx2any'', partly its philosophy, and partly the design of ''m4''. !! ''m4'' quoting and abbreviation quoting ''stx2any'' uses the native ''m4'' quoting mechanism for its ordinary quoting job. The ''m4'' quoting mechanism is actually quite elegant: quoted text begins from a backquote (w_bq) and ends in an apostrophe ('). Quotes can be nested, so if you need literal quotes ``like this'', all you have to do is write ```like this'''. With ''m4'' quoting, you can quote macro calls, as in ``w_paragraph''. Abbreviations (the heart of Stx) are more problematic, because they are processed before the ''m4'' processing phase takes place. But all abbreviations are defined to be highly contextual: for instance, the begin emphasis markup is required to have a left separator (space, open parenthesis, ...) on its left side and a nonblank character on its right side. Because the backquote (w_bq) is not considered to be a left separator, you can quote emphasis markup as if quoting ''m4'' macro calls, and get e.g. `/'usr by writing ``/''usr. All emphasis constructs also put quotes around the emphasised text, so literal ''/usr'' works without any quoting. Alternately, you can put markup out of context: for example, writing // in the middle of the line does not cause a line break. w_autorefer(Link abbreviations) can be quoted by quoting the _last_ square bracket in them. !! Quote quoting When you have a quoting mechanism, you have to have a quote-quoting mechanism: otherwise, you have no way to include a literal quote in your text. Simple instances of quote quoting are handled by the nesting of quotes: whenever you write quotes inside quotes, the inner quotes are preserved. Unmatched quotes are more problematic. Especially the apostrophe (i.e. ''m4'' closing quote) is a common character. ''stx2any'' strives for keeping your apostrophes from interfering with its ''m4'' machinery (which makes heavy use of quoting) by quoting them into calls to w_macro(`w_apo'), which are eventually converted back into apostrophes. But there is the problem that sometimes your apostrophes _are_ meant to be ''m4'' quotes. ''stx2any'' takes this into account by applying the w_macro(`w_apo') rule only to those apostrophes that do not have a matching backquote (i.e. ''m4'' opening quote). This, in turn, means that if you need an unmatched apostrophe _within quotes_, you have no option but to write w_macro(`w_apo') there yourself. A whole another problem is the lone open quote, for which there is no way of writing without changing ''m4'' quoting rules. If there is an unmatched backquote in the source, ''stx2any'' reports this as an error. The macro w_macro(`w_bq') temporarily changes ''m4'' quotes and puts a literal backquote in the output. So if you need a backquote (w_bq) in the output, write w_macro(`w_bq') (or w_macro(``'w_bq`'') if there are adjacent words) instead. And thank god[[ or Gaea, destiny, what have you ]] that you don't need backquotes all that often. !! Output format quoting To enable easy mixing of direct output format code and ''stx2any'' markup, ''stx2any'' by default does not perform any quoting whatsoever for constructs in the output language. There is a command line option, ''--quote'', which will quote all characters that are somehow magical in the output format so that they will appear literally in the output. The magical constructs are, by output format: HTML and DocBook:: less-than and greater-than signs (''w_lt'' and ''w_gt''), ampersands (''w_amp''). man:: lines beginning with dots (''.'') or apostrophes ('), backslashes. LaTeX:: words beginning with backslashes (''w_bs''), and any curly braces (''{'' and ''}''), ampersands, underscores (''_''), carets (''^''), tildes (''~''), dollar signs (''$''), hashes (''#''), percent signs (''w_pct'') and probably a few others I've forgotten... The ''--quote'' option works by converting these special characters [[-except underscores and dollar signs, which are quoted by the separate option ''--quote-me-harder''.-]] into macro calls, which eventually get converted back to the literal representation of that character in the requested output format. Often this is just the character itself, if it happens not to be magical in that output format. If you decide not to use automatic output format quoting, you can call these macros yourself every time you need some character that might be magical. The macros are: * w_macro(`w_us') for underscore (w_us) * w_macro(`w_lt') for less-than (w_lt) * w_macro(`w_gt') for greater-than (w_gt) * w_macro(`w_amp') for ampersand (w_amp) * w_macro(`w_bldot') for line-beginning dot (.) * w_macro(`w_blap') for line-beginning apostrophe (') * w_macro(`w_bs') for backslash (w_bs) * w_macro(`w_obr') for open curly brace (w_obr) * w_macro(`w_cbr') for close curly brace (w_cbr) * w_macro(`w_ct') for caret (w_ct) * w_macro(`w_td') for tilde (w_td) * w_macro(`w_dol') for dollar sign (w_dol) * w_macro(`w_hs') for hash sign (w_hs) * w_macro(`w_pct') for percent sign (w_pct) ''--quote-me-harder'' is a separate option because underscores and dollar signs are especially problematic. An underscore is a valid character in a macro name, and blindly quoting underscores will break your markup seriously. At the moment, ''w_'' macro calls are protected against underscore quoting. Dollar signs are also sometimes used in macro definitions, and quoting them will break the macro definition. ! Compatibility As every creator has high hopes for his thought-child, I, too, would like to see Stx taken into widespread use and implemented many times.[[-The chances of this actually happening are quite small, because there are many competing formats out there, and everybody seems to have own personal preferences about what the syntax of structured text should be like.-]] There is, however, the problem that because ''stx2any'' allows (in fact, encourages) extending the vocabulary with your own ''m4'' definitions, correctly reimplementing Stx would require you to build a ''m4'' interpreter in the process, and if you did that, there would seem to be little point to reimplement Stx.[[-A similar situation applies for LaTeX, whose proper reimplementation will require reimplementing at least part of TeX, to allow for user-defined commands, environments and the like.-]] Because of this, I suggest compatibility /levels/, which describe the degree to which a particular implementation supports Stx. They're meant to make a progression from more important things to less important ones. I would deem implementation on the first level ("abbrev level") to be quite sufficient for, for example, wiki markup, and the second level ("markup level") sufficient for most purposes. On the fourth level, the syntax supported is mostly equivalent to that of ''stx2any''. Support for w_autorefer(Link abbreviations) is orthogonal to these compatibility levels and regarded as an optional extension to them. abbrev level:: This level has support for abbreviation-based markup: paragraphs, different kinds of emphasis, headings, different kinds of lists, preformatted blocks, hard linebreaks, section breaks, and metadata headers (but support for footnotes and special characters such as long dashes, ellipses or copyright signs is not required). Emphasis constructs should only be recognised when there is an opening and closing emphasis mark. Emphasis should not be allowed to span paragraph boundaries. An emphasis marker (asterisk, slash, double-apostrophe, etc) is recognised as an opening mark when preceded by a left separator and followed by a non-blank character; and as a closing mark when preceded by a non-blank character and followed by a right separator.[[-Separators include blanks, dashes, apostrophes and quotation marks, in addition to which different kinds of opening parentheses are left separators, and punctuation marks and different kinds of closing parentheses are right separators.-]] Emphasis must not be empty but can be only one character long. markup level:: This level has support for (almost) all non-extension-oriented markup: all the contructs on abbrev level, plus footnotes, everything in the sections "environments" and "macro-based markup" except w_macro(`w_crosslink'), w_macro(`w_index') and w_macro(`w_indexword'). Support for ''m4'' quoting is required, though only one level (that is, no need to implement nested quotes), as well as w_macro(`w_apo'), w_macro(`w_bq') and the rest of special characters described in the section "output format quoting". When (part of) something is ''m4'' quoted, it should not be considered for macro expansion or other kinds of processing. extension level:: This level is meant to support users using their own extensions, as long as they don't do anything complicated. All the constructs on markup level are supported, plus proper ''m4'' (nestable) quoting and everything in the section "extension markup". In short, everything described in this document, with the exception of w_macro(`w_crosslink'), w_macro(`w_index'), w_macro(`w_indexword') and some esoteric subtleties of abbreviation quoting should be supported. Implementing w_macro(`w_define_env'), w_macro(`define') and friends will require at least some kind of macro processing capability. On this level, you don't have to implement arguments to macros; that's on the next level. full compatibility level:: All ''m4'' constructs not already mentioned should be supported, in addition to the stuff in extension level. This includes a _lot_ of stuff, and means you ended up reimplementing ''m4'' after all. stx2any/examples/accreditions.txt0000644000175000017500000001641610423671243021164 0ustar pkalliokpkalliok00000000000000w_title(Accreditions of ideas behind structured text)dnl w_doc_id(stxaccred)dnl w_author(Panu A. Kalliokoski)dnl Stx and its implementation, ''stx2any'', have not been developed as casual hacks. They benefit of the traditions (in some cases not more than a few years old) of typography, markup languages, plaintext markup, Unix, functional programming, literate programming, and web authoring. This document tries to record the origins of most ideas. using structured plaintext as a generic authoring tool:: This idea definitely comes from wikis. They are a prime example of how convenient and fast authoring can be. emphasis rules:: These were developed from my earlier work, a heuristic text-to-HTML converter. I think these proper, traditional emphasis rules are one of the most important aspects of Stx. The ''literal'' emphasis was motivated by Zope structured text. header blocks:: RFC822 mail headers. explicit markup:: This arose naturally from the choice of using ''m4'' as an implementation language. This explicit markup thing I deem one of the biggest advantages over other "rich" structured texts, which tend to be really syntax-heavy. We use abbreviation syntax for things that have natural abbreviations or are written a lot, explicit markup for other things. environment and counter system:: From LaTeX, of course. indentation system and processing blocks line by line:: The way of using indentation comes partially from Python and partially from PikiPiki (which probably got it from Python). Sub-character indents were a late addition to accommodate the complex structure of lists. Processing blocks line by line also comes from PikiPiki. It is a great idea, freeing us from complicated analysis in the parsing phase, and leaving empty lines for what they are good for, that is, denoting paragraphs. If we processed block types paragraph by paragraph, we would have to require empty lines in all kinds of places were they might be unnatural (such as the end of a list). using ''sed'' and ''m4'' for the implementation:: Well, this was indirectly motivated by a discussion with Dirk A. Froembgen, where I talked about how the ultimate macro processor would have custom-syntax (regexp?) macros and Dirk stated that this was actually not the job of the macro processor but possibly rather a separate parsing phase. (Macro processors are good for building text, let them stay so.) For simple text producing (even if ''stx2any'' is not that simple), macro processors are superb. They are concise, efficient, natural and easy to program. They are not very good as programming languages, but their natural "functionality" (= semblance to functional languages) makes them higher-level than, say, C or Java. But why exactly ''sed'' and ''m4''? Why not Perl and ''cpp'' (or why not make it all in Perl)? Well, first, ''sed'' and ''m4'' are practically everywhere. Besides, ''m4'' is a really good macro processor, and gives us mechanisms of abstraction (such as diversions and runtime combining of definition files) which would require work to implement in many other languages. ''m4'' is also a consistent and relatively elegant language, and gives the users of ''stx2any'' rich facilities for defining their own markup. Not to mention that Perl is actually a bloated-off piece of shit. (Except for those who actually use it...) As for ''sed'', I have to admit that I like its clumsiness, weird looks, and unbelievably weird semantics. using pipes:: Pipes are a beautiful programming construct, and their power is well demonstrated by the Unix tradition and probably especially the family of ''troff'' tools. Of course, pipes were a natural choice because of the two-phase processing in ''stx2any''. ''stx2any'' may well start some 8 processes when invoked! Pipes also make it more easy to debug the program when something goes amiss. It is nice to be able to inspect the result of the conversion in different phases of processing. That is part of "the power of plain text" (not as opposed to binary data, but as opposed to intelligent data such as objects). templating system and diversions:: These come from my earlier product, a website building engine that was also implemented in ''m4''. The diversion subsystem is a really useful abstraction layer over ''m4'' diversions, which suck somewhat. the ''w_'' prefix of Stx macros:: From the website building engine mentioned in previous item. That system had no abbreviations, and I used something like `w_p' for marking paragraphs! I think it strikes a good balance between brevity and syntax-share. passing HTML, LaTeX etc. directly through:: This is a natural consequence of ''m4'' as an implementation language, and was also present in the aforementioned website templating system. I noticed how handy it is when I used that system. Linuxdoc's wiki markup does this too. special characters: quotes, long dashes, ellipses, ...:: Mostly from LaTeX, but some were motivated by Textile. The rules for quotes and long dashes were my invention, and I'm very content with them. linking macros and link abbreviations:: These are from my experience with web authoring and wikis. There are many kinds of links, and providing semantically sensible categorisation of them requires careful thought about what we are trying to _do_ with the link. Different link categories also tend to produce different results in different output formats. The idea of ''gather_stx_titles'' is based on the aforementioned website building system. Link resolution in link abbreviations arose from reflection on the way people process links when they read plaintext. The idea of the syntax of link abbreviations mostly comes from Markdown, except label syntax comes from AFT, and automatic labeling of headings is a great idea stolen from ReST. syntax for line breaks:: An earlier project of modifying PikiPiki, which got it from LaTeX and poetry. syntax for footnotes:: Mostly plaintext tradition, and the act of noticing that footnotes are like parentheses, only stronger. floats:: LaTeX. But the addition of making margin paragraphs floats, and the float type resolution system, are my additions and I think they are very good. syntax for tables:: LaTeX. This, too, I deem one of the big advantages of Stx over other "rich" structured texts: you don't have any weird syntax for tables, you just write them as they seem natural. Very nice. The "||" marker is a natural extension of the "//" syntax, and sure looks better (and uses less syntax space) than "w_amp". paragraph system:: Plaintext tradition, LaTeX, ''troff''. I came up with the idea that _sometimes_ even a lone newline might be relevant markup (this is not used very much in Stx). It would also make sense to translate paragraphs to different stuff based on context -- for example, within tables, into table groups. block system:: numbered list syntax, heading syntax:: From my work on PikiPiki. These were tried out and found good. preformatted (literal) block syntax:: From PikiPiki. This, too, is a great advantage, because it allows us to write e.g. program code as in a normal source file. Indented literal blocks are good for short passages, but hell for proper literate programming etc. literate programming:: Donald Knuth. regression testing:: tee-hee...