Setup files: processing and deployment

[Yves Forkl]

Hi all,

I am trying to re-organize the files of my Lout-based system, in order
to clearly separate my modifications to Lout's setup files from their
pristine version. The set of modified files is meant to reside in a
central place, i.e. not be put alongside with the documents processed.

While being familiar with the concepts of @Include vs. @SysInclude etc.
and having been successful in tweaking Lout's setup files to make it do
(almost) everything I wanted it to, I am still missing some important
information that I could find nowhere in Lout's documentation.

1) In which order does Lout process the setup files, and which is the
relationship between them? I am especially curious about the role of
standard.ld.

2) I've been systematically using symlinks from my setup files into the
Lout library and database directories, in some cases replacing the
original file. Is this a reasonable approach? (Lout seems to compile
some of the setup files, e.g. standard.ld, which left me with "fatal
error: cannot write to database file /opt/lout/lout.lib/data/standard.lix".)

3) How can I keep the modifications to the original Lout installation to
a minimum, say, like just using a reference to a kind of "root" file of
my modified setup? Would this have to be done in standard.ld?

I hope someone can shed some light, or recommend best practices for
keeping modifications to Lout's setup files in a separate layer somehow.

Yves

[Jeff Kingston]

Post by Yves Forkl
Hi all,
1) In which order does Lout process the setup files, and which is the
relationship between them? I am especially curious about the role of
standard.ld.

In the order it encounters them. It encounters standard.ld on
line 488 of file bsf.

Post by Yves Forkl
2) I've been systematically using symlinks from my setup files into the
Lout library and database directories, in some cases replacing the
original file. Is this a reasonable approach? (Lout seems to compile
some of the setup files, e.g. standard.ld, which left me with "fatal
error: cannot write to database file /opt/lout/lout.lib/data/standard.lix".)

You need to distinguish between Lout source files like bsf, dsf, bookf,
and book, and database files like standard.ld (anything ending in .ld).
Lout source files are simply read, so symlinks to those are fine. But
database files are accessed via an index file, a .li file (or .lix
temporarily while it is being built). When you ask to access a database
file, Lout's first step is to check whether there is an index file with
the same name (only .li instead of .ld) alongside it in the directory.
If there is, and the timestamps are OK, it uses that file, otherwise
it builds it first.

Clearly if you have a symlink to the file you will be in trouble,
since Lout sees the link name, not its value, and the link name does
not include the parent directory. Dropping the .ld from the link name
and adding .li will not find the existing .li file.

However, I don't see why there should be a problem with standard.ld,
because it is accessed via @SysDatabase { standard }, which means
that Lout supplies its own path to this file by prepending the name
of the Lout system database directory to it. I can't see why Lout
should be accessing this file under any other name.

Post by Yves Forkl
3) How can I keep the modifications to the original Lout installation to
a minimum, say, like just using a reference to a kind of "root" file of
my modified setup? Would this have to be done in standard.ld?

The basic problem here is that @Include expects a single string, there
is no way to (say) concatenate the value of a symbol to a string and
use that as the name of the file to include.

But beyond that I think it would all depend on precisely what you were
trying to do; I think we would need to get down to details.

For myself I can say that all I ever need to do is what it says in
Section 4.1 of the user's guide: copy setup files from the standard
directory to the directory of the current document, change @SysInclude
to @Include for those files, and then fiddle with them. This has
always worked well for me, for many years now. You might look at
the part near the end of the section, which explains how to merge
all the setup material into a single file. Perhaps that is what
you need; then to change setups you just need to change a single
@Include, to include one of these merged setup files.

Keep asking by all means if there is more to the story.

Jeff

[Yves Forkl]

Hi Jeff,

thank you so much for your explanations concerning the processing of
setup files. In fact, as I had been using setup files modified by
someone else, I was a bit puzzled at first and it took me some time to
sort out how they work together.

By now I have managed to organize my setup files in a way that my Lout
document just needs to have a single @Include at the beginning (plus a
@Database instruction for my references) which will have Lout include
all the other setup files, that I have copied and then modified, like
you have recommended as good practice (following Section 4.1 of the
User's Guide).

Since I want to be able to reuse the same set of modified setup files
with different documents, I keep them in a "central" place, rather than
putting the setup files alongside with the document. So I use an
absolute path in the @Include instruction (a bit inconvenient, but as
you said there is no variable expansion available here, so it's OK).

So far this works for me, but I wish Lout was a bit more modular in its
setup files. For a "book" type document, I had to copy and modify 2 of
Lout's include files and 3 of its database files, often just for a few
changes like differently localized terms. Keeping my version up to date
with future Lout releases will require me to carefully revise the whole
file. For instance, when I just want to modify the language-specific
words, it would be convenient if they were contained in a file of its
own rather than in standard.ld: the confines of my changes would then be
easier to locate, and standard.ld would not have to change. (However, I
would need to copy it so that I can have it include my copy of the file
with language-specific words.)

But all in all, Lout's setup files are fine the way they work.

Yves