Conference vaxuum::document_ft

The "model" of bookbuilding is that you simply point at the
profile as your input file and the book gets built.  We do
a "bookbuild" because we find the <PROFILE> tag in the file,
not because you "told" us to do a bookbuild on the command line.

The "model" of element (chapter) building is that you point 
at the element file as your input file AND you point back at
the profile to tell us what book this element belonged to.
That is why we used the qualifier /PROFILE instead of 
/CROSS_REFERENCE.

These models for bookbuilding and element building are based on
the idea that you ought to have a simple command line and that
the CRF file is not something you want to be concerned with.
The CRF file will simply sit in the same directory as the profile.
If we could have made it invisible, we would have.

This model is based on our assumption that you are a naive user, 
who wants the system to take care of details such as CRF files.
Most people who WORK for Digital (as opposed to its customers) 
are not at all naive.  They have multi-valued logical names, 
for example, and want to put their symbol tables elsewhere -- 
probably on other nodes!  :-)

(If CUSTOMERS are not naive, it is because we usually give them systems 
that force them to shed their naivete in order to get any work done!)

So, you are not supposed to supply us with a /PROFILE qualifier when
you do the bookbuild.  If you do, we'll try to LOAD a CRF and the first 
time around you won't even have one.  When we find the <PROFILE> tag in
your source file, we'll know enough to produce a CRF file using the
profile's filespec, with only the filetype changed to CRF. We warn you
not to delete, rename, or move the CRF file after the bookbuild.

When you want to process one of the elements, you must supply us 
with a /PROFILE qualifier that points at the profile (and because the 
CRF is in the same place, it also points at the CRF).  (If you care about 
having the out-of-element references resolved and having the chapter numbering
be correct, and if you want the CRF to be updated with any changes that
you have made to the element.)

Well in some respects I could consider myself a naive user, but others
not necessarily.  What I'm trying to accomplish is to have a large team
of writers working on the same book.  Large being 9-12 and the book is
broken into roughly 8-10 chapters.  Some or all of the writers may
have to work on some or all of the chapters.

I set up a model for book
and element building in a manner similar to developing software.  Primarily
since the writers are actually developers.
This model has a two tiered directory scheme, where all users have access
to a common set of directories, and have shadow or work copies of most
of those directories in their own tress.  We're also trying to manage
our sources and builds with DEC/CMS and DEC/MMS.
To prevent having to fetch all the sources for each book build, the source
directory logical name points first to the user's source directory and then
to the common source directory.  We want the results from a book or an element
build to potentially be placed in the common directory to try and keep the
cross-reference file up to date.

My question I guess is:  Can we do what we want with DOCUMENT T1.0?  And
in any case, shouldn't DOCUMENT be able to handle a multi-valued logical
name the same way an editor can?  Since DOCUMENT is "updating" the
cross-reference file, shouldn't it create the new version in the same
location it found the previous version?

Please, this is only a nit, and I can probably come up with ways around
it.  It just seemed strange...

-tl

    It seems to me that if the profile and its CRF are in the common
    directory and each writer has his/her own element files in a local
    directory, then, once the initial bookbuild is done, the writers
    can each work independently, referencing the CRF in the common area.
    (Accesses to the CRF cause it to be locked while it is open and
    in the process of being potentially changed, so occasionally
    two writers may attempt independent element builds and one will
    be locked out.  Also, a bookbuild will lock any current CRF until
    it has produced a new one.  So, accessing of the CRF was designed
    to accomodate exactly what you are doing.  
    
    What we did not plan for was multi-valued logical names.  I don't
    even know how you access a file through a multi-valued logical
    name.  A naive programmer like me would assume that if RMS can
    handle a logical name, that it can also handle a multi-valued
    logical name.
    
    You will be in trouble if you use <condition> tags, however, unless
    all the writers are using the same <set_condition> tag value or
    the same /CONDITION qualifier.  If you have two conditions, say
    VMS and ULTRIX and half the writers want the VMS condition turned
    on and the other half want the ULTRIX condition turned on, then
    you will have to have two copies of the profile in separate directories
    so that the CRF file for the VMS condition is separate from the
    CRF file for the ULTRIX condition.
    
    I'll check into multi-valued logical names.  For the moment, it
    looks like you have to use single valued logical names, and all
    the writers have to be able to write to the directory where the
    profile and its CRF reside, although their individual element
    files can be in their own directory.
    
    If two writers are working on the same element, are they editing
    the same file? and are you using CMS to combine their edits, or
    do you have the element broken out into sub-element files?  If the
    latter, are planning to use the /ELEMENT qualifier?  I'd like to
    know how that goes, if so.
    

I'm not sure how the editors and like handle the RMS end of dealing
with multi-valued logical names.  I suspect you have to preceed the
SYS$OPEN request with a SYS$PARSE and a SYS$SEARCH to get the actual
device/directory specifiation for the CRF.

Two writers will be working on the same element at the same time, but
in different files, i.e. the elements are further subdivided into 
multiple files.  Currently those are being <INCLUDE>'d by the
element files.  I haven't had time to investigate /ELEMENT, but from
looking at the help file, I will!

By the by, what was CMSDOC and whats become of it?

-tl

    
    CMSDOC was a set of command procedures designed to provide file
    access protection back in the days when CMS (version1) didn't
    provide protection. It also simplified the command interface.
    Today, it is still used here locally to provide captive accounts
    on the central machine for writers to store and retrieve files,
    but they can't do anything else on the production machine.
    
    patti
    
    

    I think we are  doing whatever we need to do to get the multi-valued
    logical name translated OK, but somewhere we are simply chopping
    a character or two off the end of the filespec.  Note that in the
    error message that Todd reported in the original note the tag 
    translator says it is looking for mumbledy:file.CR instead of
    mumbledy:file.CRF.
    
    And the error reported is "file not found" rather than "directory
    not found", etc.
    
    SOmetimes the evidence stares you in the face and you don't see
    it...
    

I had noticed the missing "F" in the message but thought it was an error
in the message, not a pointer to the real problem.  Oh well...

I tried using /ELEMENT and can't see that it did anything for me.  I
observed that it used the file specified as the argument to /ELEMENT to
be included in pass 1 of the tag translator.  I expected the output then
to look as though it had been "extracted" from the middle of a bookbuild, 
or close to it.  Instead, I can't see what the /ELEMENT bought me?  My 
document structure is as follows:

FS.GNC - The profile file
	
	<PROFILE>
	<ELEMENT>(EPIC$DOC:fs_front.gnc)
	<CONTENTS_FILE>
	<ELEMENT>(EPIC$DOC:fs_system_overview.gnc)
	<ELEMENT>(EPIC$DOC:fs_system_interfaces.gnc)
	<ELEMENT>(EPIC$DOC:fs_network_features.gnc)
	<ELEMENT>(EPIC$DOC:fs_system_management.gnc)
	<ELEMENT>(EPIC$DOC:fs_simulators.gnc)
	<ELEMENT>(EPIC$DOC:fs_general.gnc)
	<ELEMENT>(EPIC$DOC:fs_documentation.gnc)
	<ELEMENT>(EPIC$DOC:fs_training.gnc)
	<ELEMENT>(EPIC$DOC:fs_back.gnc)
	<INDEX_FILE>
	<ENDPROFILE>


FS_NETWORK_FEATURES.GNC - Chapter 3 in the document

	<COMMENT>(****Version 1****)    
	<CHAPTER>(Network Features\network_features_chap)
	<INCLUDE>(EPIC$DOC:FS_NF_MDR.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_HSS.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_TRAF.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_ACA.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_AC.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_ROUTING.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_ONALS.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_DNI.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_OOS.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_CONFIG.GNC)
	<INCLUDE>(EPIC$DOC:FS_NF_RCV_PROV.GNC)


When I process FS_NF_AC.GNC (just a section in the chapter) with the 
following command:

	$ document/noprint/profile=epic$common:[obj]fs -
		/element=epic$doc:fs_network_features -
		epic$doc:fs_nf_ac soft.spec ln03

the output file looks as though I never even specified the /ELEMENT or
the /PROFILE, i.e. the <HEAD1> the section starts off with becomes a
top level heading and not a heading within chapter 3.

Is that the way its supposed to work?

-tl

    NO, that is not how it is supposed to work.  Except for the page
    numbers, and the layout on the page, the "included" file that you
    name as the input file on the command line should have all the
    numbers that would be there if you had printed the whole chapter.
    
    THus, the section heads, figures, examples, etc, should all be
    numbered exactly as if the pages had been cut out of the middle
    of the chapter.  
    
    Looks like we need some more testing...
    

    We have made some changes for FT update that will make /ELEMENT
    behave a little more like what you would expect.  On the other
    hand we are probably going to put some restrictions on what you
    should expect /ELEMENT to do.
    
    The original intent was allow the processing of templated material,
    such as appears in a reference book on a piecemeal basis, without
    having to process a large part of the book, each time you want to
    see your templated description of some command for example.
    
    But it figures that people will want to process any snippet of
    chapter 7, section 4.3, that includes table 7.4 and example
    7-3.  I can't give you all the rules here, but it will do a
    better job than you reported in reply .7.
    
    bill
    

Great!  Anxiously awaiting the FT update.

-tl