Bug 122720 - Handling of templates potentially unclear in respect to where files are stored
Summary: Handling of templates potentially unclear in respect to where files are stored
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
unspecified
Hardware: All All
: medium normal
Assignee: sdc.blanco
URL:
Whiteboard: target:7.2.0 target:7.1.0.0.beta2
Keywords:
Depends on:
Blocks: Help-Changes-Features
  Show dependency treegraph
 
Reported: 2019-01-15 08:49 UTC by Heiko Tietze
Modified: 2021-01-07 22:14 UTC (History)
3 users (show)

See Also:
Crash report or crash signature:
Regression By:


Attachments
Screenshot of potential help page about templates and filesystem (191.18 KB, application/vnd.oasis.opendocument.graphics)
2020-12-16 00:16 UTC, sdc.blanco
Details
updated version of potential help page about templates and filesystem (191.56 KB, application/vnd.oasis.opendocument.graphics)
2020-12-17 11:59 UTC, sdc.blanco
Details
Screenshot of revised section on Categories and related warning (32.72 KB, image/png)
2020-12-18 12:38 UTC, sdc.blanco
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Heiko Tietze 2019-01-15 08:49:17 UTC
Please verify and improve if necessary this section. The original request comes from bug 122427.
Comment 1 Commit Notification 2020-12-06 12:02:00 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/a2bd1ce7cf53abd37db55422c9b99a4e50d9d463

tdf#105719 tdf#122720 tdf#107229 help for making default template
Comment 2 Commit Notification 2020-12-07 07:34:15 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "libreoffice-7-1":

https://git.libreoffice.org/help/commit/e2c545ce9755cbdbcd02be09c963da8566386446

tdf#105719 tdf#122720 tdf#107229 help for making default template
Comment 3 sdc.blanco 2020-12-16 00:16:46 UTC
Created attachment 168211 [details]
Screenshot of potential help page about templates and filesystem

Maybe I closed this bug too quickly.  But maybe it is not necessary to "reopen" if the attached proposal starts to approach what is wanted/needed.

I have tried to write a comprehensive overview of the interaction between the filesystem and the template manager.  

Comments, feedback, suggestions, objections, etc. are welcome.

The focus of the proposal is only to communicate about how the Template Manager works (at present) in relation to the filesystem (though it silently passes over a few quirks, which are filed as bug reports).
Comment 4 sdc.blanco 2020-12-16 00:30:49 UTC
@Peter Toye -- if you are still interested in this topic, then I will be glad for your feedback.  I have tried to respond to the questions you raised in the meta bug 101435.
Comment 5 Peter Toye 2020-12-16 10:16:10 UTC Comment hidden (off-topic)
Comment 6 Peter Toye 2020-12-16 10:18:14 UTC Comment hidden (off-topic)
Comment 7 Heiko Tietze 2020-12-16 12:10:55 UTC Comment hidden (off-topic)
Comment 8 Peter Toye 2020-12-16 12:27:58 UTC Comment hidden (off-topic)
Comment 9 Peter Toye 2020-12-16 12:53:32 UTC
I've now had a quick look at the documentation - it seems fine to me st a first glance. I'll give it more time later. 

It's not exactly this bug (so a bit off-topic) that worries me now. I have some templates which were saved by earlier versions of LO. These don't appear in the Template Manager. Wouldn't it be a good idea to be able to import templates from earlier versions, or am I missing something?
Comment 10 sdc.blanco 2020-12-16 13:10:01 UTC Comment hidden (off-topic)
Comment 11 Peter Toye 2020-12-16 15:52:13 UTC Comment hidden (off-topic)
Comment 12 sdc.blanco 2020-12-16 16:15:59 UTC
(In reply to Peter Toye from comment #11)
> Ah - I found that you need to quit LibO and restart it for changes in paths
> to take effect! 
I see that claim from time to time.  But when I use the Edit Paths dialog for templates, I "apply" my change, before clicking OK.  Then path changes are visible in the template manager.  (It is necessary to restart the template manager, after a path change, probably because this information is loaded when TM started, but is not subsequently checked while open.)

(I have resisted writing that LibO needs to be restarted -- to avoid promulgating superstitious behavior.  So far, have not encountered a situation where application restart is needed -- but will be happy to document it, if it is true.)

(even my "apply" might be superstitious, have not tested systematically yet)
Comment 13 Peter Toye 2020-12-16 17:58:09 UTC Comment hidden (off-topic)
Comment 14 sdc.blanco 2020-12-17 00:24:28 UTC
(In reply to sdc.blanco from comment #12)
> (even my "apply" might be superstitious,...
It is.  (using 7.2.0.0.alpha0+)

"OK" alone seems sufficient in Options to change paths, w/o restarting application, and have changes be visible when opening Template Manager.

"Default" button works (in Options) to reset User Paths to "factory setting"
Comment 15 sdc.blanco 2020-12-17 11:59:47 UTC
Created attachment 168253 [details]
updated version of potential help page about templates and filesystem

added example to "Working with Template Names" section
added mention of Default button
added warning about renaming/deleting categories (and filed bug 138883 to make the warning unnecessary)
Comment 16 Peter Toye 2020-12-18 10:59:28 UTC
This is a great improvement. Thanks.

I have two comments, though.

1) It doesn't explain the concepts behind "Title" and "Category" - it rather assumes that the reader knows what these are. Is this in some other page? If not, I think it needs to be somewhere. A lot of technical docmentation tends to use concepts which are 'obvious' to the writer, but not to the reader :)

2) While it explains the relationship between directory names and categories very well, it doesn't say what happens to the category of a template in the top-level directory of the template path.

For instance there could be a template xxx.ott in (templates) - what category is it in? There isn't a "none" category in the Template Manager. Should there be?

I have to say that this relationship worries me a bit and the need for bug 138883 confirms this.
Comment 17 sdc.blanco 2020-12-18 12:38:26 UTC
Created attachment 168293 [details]
Screenshot of revised section on Categories and related warning

(In reply to Peter Toye from comment #16)
Thanks Peter.  Grateful for your comments.
 
>1) It doesn't explain the concepts behind "Title" and "Category" - it rather
> assumes that the reader knows what these are. Is this in some other page? 
As starting point:  page is conceptualized as ‟technical documentation” –  a supplement to other pages.  Assumes that user comes to this proposed page when not satisfied with existing LO tools for template management, or curious to understand how it all works.  

Note this proposed page starts by highlighting the ‟standard” commands as ‟recommended” approach.    

About ‟Title” and ‟Category” – 

Currently on offer: 

‟Save as Template” (for the File > Templates > Save as Template command)
https://help.libreoffice.org/7.0/en-US/text/shared/01/01110300.html

and ‟Manage Templates”  (for the Template Manager  File > Templates > Manage Templates)
https://help.libreoffice.org/7.2/en-US/text/shared/guide/template_manager.html

‟Manage Templates” is probably the ‟main” or ‟first” help page for most users, where the plan is to add a link (at bottom in Related Topics) to the proposed page here.

(Almost finished with an updating of that page – but mostly just to correct mistakes in labels, instructions, and add icons – if you see an obvious place on that page to address the question you raise, then I will be interested to hear your suggestion.) 

There is not ‟Introduction to Templates” guide page – afaik – file an enhancement request if you think it is needed.  But there is also a whole chapter in the "Getting Started" Guide  (link in the Related Topics section of "Manage Templates") about templates. 

> 2) While it explains the relationship between directory names and 
> categories very well, it doesn't say what happens to the category of a 
> template in the top-level directory of the template path.
The direct answer to your question is:  "My Templates" category.
The relevant information is in the "Categories" section, but apparently too implicit? Can you see a way to improve the formulation?

> For instance there could be a template xxx.ott in (templates) - what
> category is it in? There isn't a "none" category in the Template Manager.
> Should there be?
See bug 138975 
 
> relationship worries me a bit and the need for bug 138883 confirms this.
Little need for worry.  (some improvements are definitely needed, but you can safely use and enjoy the Category feature.  Here are a few "rules of thumb":

1.  Follow the warning in the attached file here.
2.  Only put template files in your "category" subdirectories.  
3.  Know that (for now) "deleting" a category also deletes the contents of its subdirectory (which motivates point 2).
4.  Handle point 3 by using "Template Manager" to first "move" templates from one category to another (i.e, this moves the physical files) (if you want to keep them), then you can safely "delete" a category (in the Template Manager).

5.  The only "wonky" bit arises with those rare occasions when categories are renamed (bug 138883) or deleted (bug 132042), or with "import" (bug 138909), the Template Manager does not "refresh" automatically with these changes, so use "Settings > Refresh" and often need to change Category selection. Or simply use the (not-superstitious, and reliable) restart of Template Manager (to load the changes) -- but no need to restart whole application. 

About the attachment:  Can be used to replace the "Categories" section in the .odg file.

1.  Gives more accurate account of relation between category names and files.
2.  Gives more accurate account of "warning"  (not quite so dire).
Comment 18 Commit Notification 2021-01-07 22:14:13 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/cb92b1c7175df1d38637a5b944f9f96314d26f8b

tdf#122720 tdf#107229 new help guide about paths and templates