Issue 85426 - Document path extension properly for XAutoTextContainer.insertNewByName()
Summary: Document path extension properly for XAutoTextContainer.insertNewByName()
Alias: None
Product: App Dev
Classification: Unclassified
Component: api (show other issues)
Version: 3.3.0 or older (OOo)
Hardware: All All
: P3 Trivial
Target Milestone: 4.0.0
Assignee: Ariel Constenla-Haile
QA Contact: issues@api
: 41782 45368 (view as issue list)
Depends on:
Blocks: 121368
  Show dependency tree
Reported: 2008-01-21 10:15 UTC by mux2005
Modified: 2017-05-20 09:32 UTC (History)
7 users (show)

See Also:
Issue Type: DEFECT
Latest Confirmation in: ---
Developer Difficulty: ---


Note You need to log in before you can comment on or make changes to this issue.
Description mux2005 2008-01-21 10:15:43 UTC
XAutoTextContainer.insertNewByName() accepts a group name in the form "name" +
"*" + pathentrynumber, where pathentrynumber describes where the autotext is to
be stored. This is not properly documented. Right now the only trace of
documentation is in an Example subsection of XAutoTextContainer, which is, due
to spelling and markup mistakes, a pain to look at (and I consequently
overlooked it). It's also lacking any kind of context (e.g. what is
"AutoTextPath" ?).

I'd like the documentation improved in the following ways

1) document the groupname + "*" + number syntax at insertNewByName(). When
people use the IDL docs for reference purposes to look for information about the
parameter for a function call, they don't look in some Example subsection
elsewhere on the page. The doc needs to be together with the function call.

2) Document precisely (or link to the documentation, probably
PathSettings#AutoText) how the AutoTextPath that the number component refers to
is formed. It is apparently not simply the path found in
Tools/Options/Paths/AutoText. In my case that path lists only 1 component,
namely my local user directory. However using *0 doesn't work in my basic macro,
presumably because the shared location (to which a normal user account doesn't
have write access) is implicitly added in the front of the path. 

Related to this: the documentation to PathSettings#AutoText could be improved to
state that this is not identical to what you can configure in
Tools/Options/Paths, because PathSettings#AutoText contains the shared section
as 1st element, which is not visible in Tools/Options/Paths. The documentation
of PathSettings#AutoText should state, where this path is taken from.

3) Document the recommended way for a program to determine the proper "*" number
value. At the moment, apart from analysing PathSettings#AutoText to find a
directory that the user has write access to, I don't see how I'm supposed to
determine the correct number. Is this the only way?

Related: Please state clearly that leaving the * number out will usually NOT
work portably. It's likely to work under Windows (where users commonly have
administrator rights), but on Unix machines the shared location (implict first
element of path, used in absence of * number) is not writable by users. So when
one wants to use insertNewByName reliably, one MUST provide a * number with
number > 0.

4) Fix the markup issues in the example subsection and present working Basic
example code or at least give some context.
Comment 1 jsc 2008-01-21 10:41:08 UTC
jsc -> tl: can you take care of this. Any changes on the DevGuide will be made
in the new Wiki only.

jsc -> mux2005, ones the wiki Devguide is available you are invited to help to
improve the documentation. The same is true for the IDL documentation. Append
your extended IDLs files to an issue and submit it to me or tl for review.
Comment 2 Oliver Specht 2008-01-21 10:51:49 UTC
Target set and reassigned to me.
Comment 3 Oliver Specht 2008-05-27 13:34:29 UTC
Changing target milestone to 3.x
Comment 4 Ariel Constenla-Haile 2012-11-04 02:32:40 UTC
*** Issue 41782 has been marked as a duplicate of this issue. ***
Comment 5 Ariel Constenla-Haile 2012-11-04 02:38:36 UTC
*** Issue 45368 has been marked as a duplicate of this issue. ***
Comment 6 SVN Robot 2012-11-04 06:25:46 UTC
"arielch" committed SVN revision 1405504 into trunk:
#i85426# - Document css::text::XAutoTextContainer paths handling
Comment 7 Ariel Constenla-Haile 2012-11-04 06:27:17 UTC
Fixed in trunk