discuss: Versioning Issues (Oracle 8i HOWTO)
Subject:
Re: Versioning Issues (Oracle 8i HOWTO)
From:
Alexander Bartolich ####@####.####
Date:
16 Jun 2002 22:45:21 -0000
Message-Id: <3D0D129F.2060704@gmx.at>
David Lawyer wrote:
> [...] This would be a lot of work, but one could use a preprocessor
> like m4 so that it would generate a custom document depending
> on the versions and distribution the reader had.
Recently I got an account on a FreeBSD/alpha machine together
with the remark that Linux people in general are too lazy to
port their stuff. In a strange coincidence I also got hold of
old sparc hardware running Solaris 2.6. And of course there is
the compile farm on sourceforge.
So I'm really toying with the idea of renaming my document to
The ELF Virus Writing HOWTO, supporting three platforms.
Of course I would have to rewrite all assembly code for each
platform. And some traditional tools (like od) have a tradition
of incompatible command line options.
But I guess that about 90 % of my document can be simply generated.
There is portable source and platform specific source in different
directories. Shell scripts to compile and run it. A perl-scripts
to parse output files and write a resulting .sgml.
I also have a ./configure.pl that writes a config.mak and a
config.sgml with the same set of variables.
For example:
<!ENTITY config.OUT "out/i386">
<!ENTITY config.ELFMAGIC "0x08048001">
and
OUT=out/i386
ELFBASE=0x08048000
The Makefile uses $(OUT) to specify correct dependencies.
And $(ELFBASE) for pre-processing a C-example with sed.
SGML-code uses &config.ELFMAGIC; to explain the example.
config.sgml also contains some system entities like
<!ENTITY % calc SYSTEM "out/i386/calc.sgml">
So SGML already provides a good equivalent of #include and #define.
The only thing I'm not sure about is #ifdef.
DocBook: The Definitive Guide:
# You might use a parameter entity reference in an SGML document
# in a marked section. Marking sections is a mechanism for
# indicating that special processing should apply to a particular
# block of text. Marked sections are introduced by the special
# sequence <![keyword[ and end with ]]>. In SGML, marked sections
# can appear in both DTDs and document instances. In XML, they're
# only allowed in the DTD.[3]
Oops. I don't have a fixed date when I will switch to XML.
But eventually it will happen, so this feature looks like no-no.
> You would need an interactive website.
Assembling documents based on a questionaire is a very bold
undertaking. How do you keep track of versions? How do you
know just which variation a user looked at before she wrote
that bug report?
If you generate all possible permutations in advance you
can archive them, diff them, and proof-read them.
IMHO state of the art in regards to dynamic web documents
is tomcat/cocoon. It's usage of XML/XSLT is really nice.
But I'd say it requires significant changes to the
development process.
Right now it's quite hard to have authors and LDP server
render the same output from .SGML. Adding a pre-processor
to this can complicate matters to insane levels.
> Could lampadas handle this?
My insight into lampadas is not that solid.
But I'd say that this early in development it is not a
problem to add an optional pre-processing state for documents.
However, I think that most mirrors of en.tldp will just copy
static files. Trying to force all of them to use a
postgresql/python application just to deliver .tar.gz
is a strange idea bound to make LDP a synonym of obscurity.
