Template field on the General page of the document properties

If I have time later today, I'll fire up my old Win XP Pro SP3 netbook
(and/or the Windows 7 laptop) and test this, but it certainly works as
described on Mac OS X Lion and Ubuntu 11.04. I haven't used OOo or LO
on any of my Windows installs in some time.

--Jean

It works for me when the cursor is anywhere in any changed text, but
not if the cursor is elsewhere.

--Jean

Maybe I should create a brand-new version 3.4.3 test template instead of trying to generate a version 3.3.4 template copy. Perhaps, the UI has been altered with version 3.4.x and is not backward compatible for a version 3.3.x template anymore.

In addition, generating a template copy by double-clicking it and not getting the Template field entered could be an unimplemented "feature" in itself--a bug. Why should one manner work, but not the other?

Gary

Maybe I should create a brand-new version 3.4.3 test template instead of
trying to generate a version 3.3.4 template copy. Perhaps, the UI has been
altered with version 3.4.x and is not backward compatible for a version
3.3.x template anymore.

My copy of LO_3_4_chapter_template.ott does not show anything in the
Template field in File > Properties > General.

If I use File > Templates > Edit to open that template for editing and
then use File > Templates > Save to create a copy under another name,
the resulting template (test.ott) does not show anything in the
Template field in File > Properties > General.

However, if I open a new .ODT document from that template and then use
File > Templates > Save to save the .odt as a new template
(test2.ott), the new template does show LO_3_4_chapter_template in
that field.

In addition, generating a template copy by double-clicking it and not
getting the Template field entered could be an unimplemented "feature" in
itself--a bug. Why should one manner work, but not the other?

It's been that way for years in OOo. I believe it's considered a
feature: the idea is that for some documents one might want the
template associated with the file (so when the template is updated,
the file pops up the "do you want to update styles" message); but for
other documents, one might want them based on the template but not
associated with it.

As for undocumented: I had written this up in an earlier version of
the Writer Guide, and I thought the info was still there. Ah, well, my
memory isn't what it used to be. Or perhaps I removed it because the
info was incomplete; there seem to be a lot of non-obvious
interactions. Because of that complexity, this is one of the topics on
my list for extensive research for my proposed book on styles and
templates.

--Jean

One major problem with OOo was not knowing if some of its deficiencies were bugs that might get fixed or if some bugs would be permanent. (Both MS Word and FrameMaker still have numerous bugs remaining unfixed from well over a decade already, and newer bugs are continually being created.)

OOo would take eons in order to tackle many of their bugs, as newer bugs were likely piling up faster than their relatively few developers could fix them. LO seems to be a lot quicker. A case in point is LO's quick response to its first 3.4 release bug that would not handle edit tracking properly (where the copyedited deletions were not visible).

One problem with documentation when bugs are involved is that such documentation likely consists of workarounds--but these workarounds are not listed as being bug fixes. So, some documentation might not be accurate at some point in the future (or even needed) after any such bugs get fixed by the developers. IOW, the documents could contain much unnecessary (or possibly even nonfactual) material.

My take is that all documentation that involves known bug fixes should be disclosed as being bug fixes--even if doing that exposes the software suite to some criticism.

Gary

Hi :slight_smile:
I think it has already dealt with by having a fixed set of documentation for the 3.3.x branch and now making the newer release for the 3.4.x branch. See the gap at the right-hand-side of
http://wiki.documentfoundation.org/Documentation/Publications
Smart eh?

Some people may continue to prefer to use the work-arounds given as part of the documentation for the 3.3.x branch even after a bug has been fixed in some cases.

If you really feel the need to identify which established ways of doing things are/were due to bugs and which are/were just an alternative way or even a main way of doing things then feel free. I think Alfresco still has the folders ready for updating the older version of the documentation. Personally i think it's better to keep moving forwards where possible rather than to back-track.

The OOo devs were often able to fix bugs and they submitted many patches and updates that had already been tested by the community but Sun often disdained to accept work done by non-employees (apparently). That was part of the reason for forks such as Go-oo. It was probably also part of the reason why so much was achieved so quickly with the code in early releases of LO when Go-oo and possibly others re-integrated with LO. At least that's the impression i get after reading-up 3rd party accounts and hearing from a few disgruntled people that are much happier with LO under TDF than with anything under Sun.

Regards from
Tom :slight_smile:

One thing that you apparently do not understand is that I am not at all in favor of keeping any deadwood kludges around, as you stated, but to eliminate them in current and future docs. (I do not know how you inferred that I favor keeping deadwood. Just the opposite.)

However, if (undocumented) kludges were a part of any current templates or other docs--such as any remaining artifacts carried forward from buggy versions 1 or 2 even, just how would you any anyone else delete them if, in fact, you were not even aware of their existence in the first place?

My point is that all such esoteric workarounds put into any document, template, or master document should be adequately disclosed, so that anybody maintaining or reviewing or editing those docs would know of their existence, their locations, their effects, their reasons for existence, and whether or not they are even needed any longer. If LO or OOo were to use any such mysterious kludges in the future, they should be appropriately documented. OOo (and LO) rarely ever disclosed their former kludges in a clear, consistent manner. That's all to my point.

The only good reason that a workaround would have been used in the past was to act as a temporary band-aid approach due to a bug being present. Bugs generally get fixed, so after the bugs are fixed, the kludges should be eliminated in favor of better writing or editing practices.

Gary

Are there "kludges and workarounds" in our docs or templates?

I've got lost in this conversation, which seems to have mutated from
how templates work (and whether something we've observed is a bug or a
feature).

--Jean

Hi :slight_smile:
The 3.3.x branch was initial publicised as having "one year's support" and part of that surely has to include documentation. I get the feeling that a lot of people have forgotten about that promise but at least if documentation is there then we keep the promise and make it easier for other people to do so too, especially the Users List.

So it was really me that was saying i am in favour of keeping "old deadwood" but i am definitely not in favour of spending time on improving it.

There are problems within documentation but these seem to be being ironed out as we move forwards with the releases for the newer branches. It would be really cool and might make work easier in the future if there were comments on the documentation. I think there are some such notes in Alfresco rather than weighing down individual documents by having them embedded in some way.

I'm still not completely clear on how much of a template is retained or not in a final document but i think we have sometimes been trying to keep things light and fast for the end-users rather than for documenters.
Regards from
Tom :slight_smile:

That is my point. I would hope that none were used because if there were. it is likely that they would not be documented. However, I do not know if any still linger on as artifacts anymore.

In the past on occasion you had sprinkled around a few in some pages or another, especially when the buggy versions of master documents were involved. However, I do not recall ever seeing any editor notes or marginal comments about their use then either.

My advice is merely to prevent the future use of any kludges that are undocumented--not their use when advantageous, BTW.

Gary

Having marginal comments embedded within active source documents does not in any way bog down its use. They can serve as a cheap-and-easy form of conditional writing because the viewing (and printing) of the comments can be effectively squelched via menu commands and other options. However, if such kludges and their documentation ever become separated from each other, then numerous ambiguities as to their existence and possible usage can easily arise.

IOW, keep the kludges, if any get used, and their documents together--such as inserting marginal comments at the closest location of any workarounds.

Gary

Gary

Hi :slight_smile:
Words such as kludge and "work-around" are descriptions of types of coding. It just about stretches to documentation but for me ...

kludge = messy, inelegant coding that is a nightmare to look through. It might be original coding or it might be a patch. So, it's not necessarily a work-around. Apparently in OpenSource code people often leave a comment apologising if they have been forced into doing a quick kludge.

work-around = a bit of code that gets around a problem. It might look a bit weird if you take an overview of the entire project but it's not necessarily a kludge. It might be that perfect coding would involve a total re-write of the entire project but a work-around of just a few lines might give much the same result. A work-around might be a very elegant piece of coding and might even improve on some long-established coding.

Regards from
Tom :slight_smile:

Hi :slight_smile:
Ahhh, ok. I don't know what is in the notes but it's got to be worth having a quick look because there is likely to be some helpful stuff in there.
Regards from
Tom :slight_smile:

As an electrical engineer from the 1960s--where we programmed discrete digital electronics then a decade before there were even simple rudimentary integrated circuits--we employed machine code in low-level programming, which tended to be termed "spaghetti code." Everything back then was a kludge of sorts, out of necessity. Be advised that the Apollo command computer of the 1960s had only four KILObytes of RAM back then... The computer next to this old P4 has two million times as much RAM as standard equipment and will still install another 16GB.

Terminology is one field does not have to parallel that of another field. I am sure that most in the docs end of IT would understand what kludges or workarounds in documentation might entail.

Gary

Hi,

They can serve as a cheap-and-easy form of conditional writing because the
viewing (and printing) of the comments can be effectively squelched via menu
commands and other options. However, if such kludges and their documentation
ever become separated from each other, then numerous ambiguities as to their
existence and possible usage can easily arise.

I'm not aware of any kludges in the docs teams methods or the docs
produced. It deserves to be said that Jean Weber has brought a lot of
expertise and put in a lot of work to help us develop pretty clean and
methodical ways of doing things. Do you have any specific examples of
"kludges" to point out? If there are any, I'm sure we can find a
solution pretty quickly.

One would surely not be aware of any if they were not disclosed, now would they?

Well, Jean was the most likely editor who used them at OOoAuthors in order to get around a number of deficiencies with the master documents, mostly. The rub was that she rarely, if ever, disclosed them--unless somebody might tamper (remove) them inadvertently without realizing that they were "features" installed for some workaround or another.. Then, Jean might state that such-and-such was there for some workaround and that it should be left intact.

Other locations for some kludges might be on the title pages of the individual chapter files. Not disclosing them could "break" things, though, if other editors would work on such files without being aware of their presence.

A parallel in the computer-coding business is having a coder who might do things to enable "job security." However, I am not including Jean into that kind of group. I was coming up with hints and suggestions for some future tutorials, and disclosing workarounds was just one of those suggestions. So, I brought it up here.

In any event, I am not against the use of kludges, as they often are the only way to accomplish some objectives with non-compliant applications--like the earlier versions of the quite buggy master documents in OOo. But, to be professional, those kludges really must be disclosed whenever they are employed.

'Nuff said... I came across a bit of obsolete material recently while technical editing the "Working with Templates" chapter. One subsection refers to installing the Template Changer, which is now preinstalled in LO. So, I remedied that. There is another area where a nonexistent command is documented. So, that subsection needs rewriting, as I left it for another volunteer to finish. Should be easy to finish, though. That chapter had not been modified at all in over eight months, so it needed work.

Perhaps, some volunteer writers who work with templates, like Jean and others, might add some input to that chapter, as she is writing a book on the subject, I think. I added some simple marginal notes in the chapter about some very minor ways to beef up the chapter. Also, a version 3.4 screen capture is needed. I will let others do the screenshots.

Another area is: writers who do not follow the formatting rules concerning paragraph and character styles in the template exposition. Using manual overrides (direct formatting) is a no-no.

Gary

Gary,
I would very much like to get a copy of your edit of the Writer Guide
chapter on templates. The factual errors you found may also be present
in the Getting Started guide chapter on styles and templates, which
I've had one pass through for v3.4 but may well have missed.

The last time I checked your forum (yesterday), it had not yet been
uploaded. And AFAIK you have not put it on the LO Alfresco site
either.

Thanks, Jean

Well, Jean was the most likely editor who used them at OOoAuthors in order
to get around a number of deficiencies with the master documents, mostly.
The rub was that she rarely, if ever, disclosed them--unless somebody might
tamper (remove) them inadvertently without realizing that they were
"features" installed for some workaround or another.. Then, Jean might state
that such-and-such was there for some workaround and that it should be left
intact.

Those are appropriate and correct uses of fields, NOT (by my
understanding of the terms) "kludges" or "workarounds", and they were
documented, though I suspect the explanations have become lost over
the years. If I had infinite time, I would make sure that loss of
documentation didn't happen. When I have a chance, I'll check the
chapter on the template (and the info in the template itself) and fill
in any missing info.

Other locations for some kludges might be on the title pages of the
individual chapter files. Not disclosing them could "break" things, though,
if other editors would work on such files without being aware of their
presence.

See above.

Your general point is well taken (be sure to document the use of fields etc).

--Jean

I thought you visited the site, as I checked out the new update of the statcounter app that monitors my web sites. I got an email from them (StatCounter.com) to check out their new monitoring system. (It's free.) There were three visitors from Australia and another from New Zealand, among others today. Another was from my hometown, Milwaukee, tonight.

I would not ever place a work-in-process file on Alfresco. So far, I will stop editing and freeze the chapter file (a work-in-process) and affix a _mod_0 suffix to its filename. After I rewrite it, I will affix a _mod_1 suffix for the second edit, etc. That way (to me) is better than the OOoAuthors manner of filenaming. I will upload the now-frozen, mostly edited chapter file tonight, plus leave a link to its URL on this message board after I do so.

Gary

Thanks for the kind words, David, but many of the files are not as
"clean" as they could be and the solutions to their problems are not
easy or quick, partly because they are not consistently reproducible.
However, the problems that I am aware of (mainly related to some
cross-references becoming incorrect when individual files are combined
into a book) are not the items that Gary has been mentioning, which in
my vocabulary are neither kludges nor workarounds. See my comment on
the other thread that Gary started.

Trying to diagnose and fix the x-ref problem is a long-running
problem, going back years. TJ Frazier at OOo put some effort into it
and, I believe, filed an issue. IMO it is probably related to the fact
that many chapters began their lives as .swx files (OOo 1.x) and a few
as .DOC files (from Word 97) rather than a bug in OOo or LO
themselves. But that's a separate discussion, and I lack the energy to
go there now.

--Jean