new feature: how to document it?

(Moving discussion to documentation team ML. Please keep me in CC, I'm
not subscribed / I don't read that ML "often".)

One last question: where can I edit the help to document a new feature
I'm introducing (namely, the option that the storage value is the
index in the list)? I grepped for a string that appears in the right
help page, but no result. In particular, I did not find it in the
"helpcontent2" directory. Also, do we have our fork of the
OpenOffice.org Developer's Guide?

AFAIK, there is nothing about the MVC paradigm and its application in
database controls in the helpcontent, (...)

That's not what I meant. When I'm editing the properties of a listbox,
in the data tab and I press "F1" I get a new window entitled
"LibreOffice Help - LibreOffice Base", with content like below. That's
what I intended to change.

I tried grepping for "allows you to assign a data source" in the
LibreOffice source code to find the file I'm supposed to change, no
luck.

I added the feature that the "BoundColumn" can now be "-1" also. I'd
also like to explicitly document that "0" or empty have the same
behaviour.

https://wiki.documentfoundation.org/Documentation/Development
sends me to http://www.odfauthors.org/libreoffice/english/, but:

- This site's built-in search does not find anything when I search
   for "allows you to assign a data source to the selected control"
- "Base Guide" has nothing
- "Base Handbook", the chapter "Base H/b Ch4 Forms" could be
   relevant, but again, searching in this document (in LibreOffice
   writer), I don't find the text I want to change.

Here's the first fifth or so of the page/document I want to edit:

--------------------- BEGIN QUOTE -------------------------------

Data
The Data tab page allows you to assign a data source to the selected
control.

To access this command...
Open context menu of a selected form element - choose Control - Data
tab
Open Form Controls toolbar or Form Design toolbar, click Control icon
- Data tab

For forms with database links, the associated database is defined in
the Form Properties. You will find the functions for this on the Data
tab page.

The possible settings of the Data tab page of a control depend on the
respective control. You will only see the options that are available
for the current control and context. The following fields are available:
Bound field

If you delete the contents of the Bound field cell in the property
browser, the first field of the result set is used to display and to
exchange data.

This property for list boxes defines which data field of a linked
table is displayed in the form.
If a list box in the form is to display contents of a table linked to
the form table, then define in the Type of list contents field if the
display is determined by an SQL command or the (linked) table is
accessed. With the Bound field property, you use an index to specify
to which data field of the query or of the table the list field is
linked.

The property Bound field is only for forms that are used to access
more than one table. If the form is based on only one table, the field
to be displayed in the form is specified directly under Data
field. However, if you want the list box to display data from a table
that is linked to the current table over a common data field, the
linked data field is defined by the property Bound field.

If you selected "SQL" under Type of list contents, the SQL command
determines the index to be specified. Example: If you specify an SQL
command such as "SELECT Field1, Field2 FROM tablename" under List
content, refer to the following table:
Bound field
Link
{empty}
The database field "Field1" is linked to the field specified under
Data field.
1
The database field "Field2" is linked to the field specified under
Data field.

If you selected "Table" under Type of list contents, the table
structure defines the index to be specified. Example: If a database
table is selected under List content, refer to the following table:
Bound field
Link
{empty}
The 1st column of the table is linked to the field specified under
Data field.
1
The 2nd column of the table is linked to the field specified under
Data field.
2
The 3rd column of the table is linked to the field specified under
Data field.

--------------------- END QUOTE -------------------------------

It's in the helpcontent2 repo, git grep doesn't know about submodules :frowning:

Disclaimer: http://www.peralex.com/disclaimer.html

Hi :slight_smile:
The documentation team don't update the in-built help.

If you do figure out how to update it then it might be good to start developing wiki-pages to help make it easier for us to get involved.  At the moment it seems like it might be far to difficult. 
Regards from
Tom :slight_smile:

(Moving discussion to documentation team ML. Please keep me in CC, I'm
not subscribed / I don't read that ML "often".)

So, I managed to update the built-in help for my new feature. Now, for
the Base Handbook chapter 4: forms.

Here are the needed changes, all in section Form properties /
properties of controls / List box:

- page 23, everywhere that the property "BoundField" is referred to:
   I added (for LibreOffice 4.1) the possibility to set that property
   to -1 to get (in the database field "Data field") the *index* of
   the selected entry (or entries) in the list instead of anything
   from the table/query/... as appropriate.

That's it!

If you'd like me to upload something to odfauthors.org, I'll accept an
account and do it (preferred username: lmamane), but bear in mind I'll
most probably not contribute to documentation much.

BTW, I'm a Base developer in LibreOffice, and user of scripting; if
someone wants to work on documentation of those, I'd be happy to serve
as a technical guru for the parts that I'm familiar with for the
documentation writer :slight_smile:

Hello Lionel,

(Moving discussion to documentation team ML. Please keep me in CC, I'm
not subscribed / I don't read that ML "often".)

So, I managed to update the built-in help for my new feature. Now, for
the Base Handbook chapter 4: forms.

Here are the needed changes, all in section Form properties /
properties of controls / List box:

- page 23, everywhere that the property "BoundField" is referred to:
   I added (for LibreOffice 4.1) the possibility to set that property
   to -1 to get (in the database field "Data field") the *index* of
   the selected entry (or entries) in the list instead of anything
   from the table/query/... as appropriate.

That's it!

I will change this in the new Base-Handbook. The English version of the
Base-Handbook is edited for LO 3.6. The new German version is edited for
LO 4.0. The english version isn't published yet.

In the handbook we should only write about features, that exist. So let
us explain every new feature of LO 4.1 ind the next version of the handbook.

I haven't followed the whole discussion. As I understood first (QA-list)
it is planned to change the macro code to get the bounded value of a
listbox, not only the current (displayed) value. Why do you want to
change the property of this field to -1?

Regards

Robert

So, I managed to update the built-in help for my new feature. Now, for
the Base Handbook chapter 4: forms.

Here are the needed changes, all in section Form properties /
properties of controls / List box:

- page 23, everywhere that the property "BoundField" is referred to:
   I added (for LibreOffice 4.1) the possibility to set that property
   to -1 to get (in the database field "Data field") the *index* of
   the selected entry (or entries) in the list instead of anything
   from the table/query/... as appropriate.

In the handbook we should only write about features, that exist. So
let us explain every new feature of LO 4.1 ind the next version of
the handbook.

Fair enough.

I haven't followed the whole discussion. As I understood first
(QA-list) it is planned to change the macro code to get the bounded
value of a listbox, not only the current (displayed) value. Why do
you want to change the property of this field to -1?

The change you refer to is for the behaviour of a specific programming
interface, which used to always return the display string of the
currently selected entry, and which will now return the bounding value
of the currently selected entry (like it does for all other
controls). This is completely orthogonal / independent of the
BoundedColumn=-1 feature.

When ListSourceType is Table/Query/SQL/SQL [native], the BoundedColumn
property determines *what* the bounding value is. If it is zero, it is
the display string (that is, the first column). If it is one, then the
second column. If it is two, then the third column, etc.

Now, the new feature is that one can now set BoundedProperty to -1,
and in that case the binding value is the index of the selected
entry. That is, getCurrentValue() will return the index, the index
will be read from / written to the database field, ...