incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Uwe Fischer <uwe...@googlemail.com>
Subject Re: Conventions in help files
Date Mon, 06 Feb 2012 19:19:01 GMT
Hi,
I try to give some answers regarding Help authoring. A Google search with
"helpauthoring openoffice.org" returns some more answers, for example the
110 pages PDF guide on Help Authoring.
Unfortunately not everything that was written down in the PDF guide got
implemented, and some elements mentioned in the guide are not evaluated any
more, if they ever were ...

The id elements must be unique within the current xhp file. They are mainly
used for indexing and referencing, where the full reference is built up
using path_filename_idvalue on compile time.
We used some OOo macros when writing the Help files, so the ids were
inserted by some randomizer function. But you can use any number as long as
it is unique in the file.

The l10n values are no longer evaluated. We used it lately as a flag for
the authors: something like l10n="N" meant "new" paragraph. This did help
in syncing file contents in cvs, svn, or hg, where it was sometimes very
difficult to see which paragraph was the new one and which was the old one.

The bookmark elements with Help ID contents just are bookmarks. An example
would be:

<bookmark xml-lang="en-US" branch="hid/.uno:SomeHelpID" id="bm_id7275002"
localize="false"/>
There can be any number of such bookmarks in a file. The Extended Help text
that belongs to the Help ID given in the bookmark is the text in the next
following <ahelp> attribute within a paragraph element. So any number of
Help IDs can return the same Help text. No problem with several identical
Help IDs within the same file. But be careful when using the same Help ID
in different files. This is only allowed when those files are located
outside of the "shared" folders.
Example for a paragraph with an <ahelp> element:

<paragraph role="paragraph" id="par_id3158407" xml-lang="en-US" l10n="U"
oldref="46"><ahelp hid=".">Uses percentile scaling for font size in user
interface elements, such as dialogs and icon
labels.</ahelp></paragraph><comment>UFI: see OOo only feature "Icon theme
switching"</comment>

Note that in this example the <hid> value is a dot only. This is because
the value must not be empty. But the value is not evaluated any more. If
you find a value that looks like an old Help ID, this is not evaluated. But
keep in mind that removing that value and replacing it with just a dot
would be a translation relevant change of that paragraph. So it is not a
good idea to remove those old values for the sake of "human readability"
because hundreds of translators would need to have a look at the paragraph
later on.

You can delete all duplicate Help ID bookmarks in the same file entries if
you want - they were inserted by a script at some time.
The macros that we used to create and edit xhp files in
openoffice.orgWriter might be available somewhere as an extension
helpauthoring2.oxt. But
they had some bugs because the macro language did change from time to time
and not all macros could be changed accordingly. So it is a good idea to
use a text editor with XML syntax highlighting to edit the xhp files. To
create a new file, copy an old file and edit everything. Then enter it to
the make file and register the change in the CMS.

Your last question, where to write new Help contents, should be discussed.
AFAIK a locally installed Help is legally mandatory in some countries, if
the software is to be used in business or in governments etc. Libreoffice
uses a web based Help which defaults to the local files if no web is
available. Not every user has or wants web access when working with
OpenOffice.

Uwe

On Mon, Feb 6, 2012 at 6:16 PM, TJ Frazier <tjfrazier@cfl.rr.com> wrote:

> On 2/6/2012 11:11, J├╝rgen Schmidt wrote:
>
>> Hi Regina,
>>
>> On 2/6/12 4:50 PM, Regina Henschel wrote:
>>
>>> Hi all,
>>>
>>> I'm going to add help texts for the new line caps and for corner style.
>>> I found that the extended help tips have to go into
>>> helpcontent2\source\text\**shared\01\05200100.xhp.
>>>
>>> Inside that file the nodes get id-values. The first part is 'bm_id' or
>>> 'hd_id' or 'par_id' according to the kind of node. That is followed by a
>>> number. Does a convention exists, how to build that number?
>>>
>>> The attribute l10n had been used for the change from OOo1 to OOo2 but no
>>> longer. What value is used for content, that has not exist in OOo1?
>>> Should it be l10n="" (which means empty) or l10n="NEW"? The attribute is
>>> required.
>>>
>>> I see bookmark nodes with identical branch attribute, for example
>>> branch="hid/.uno:LineWidth" but different id-values. That makes no sense
>>> to me, because the hid has to be a unique target in the help files.
>>> Reason for the duplicate nodes?
>>>
>>> There are some remarks needed, which go beyond an extended help tip.
>>> Where should I add them, to one of the 'guide'-files or make a new one.
>>> Or exists plans to drop such information from help totally and only use
>>> a Wiki for more detailed help?
>>>
>>>
>> you haven open pandora's box and probably nobody really knows how
>> exactly it is used and were handled in the past. Or better the people
>> who knows are not really active anymore in the project.
>>
>> I have some experience with creating help files for extension but these
>> were very small and I had everything under my control ;-)
>>
>> I think Frank Peters have mentioned the help extension (xslt filter + a
>> macro collection) that can be used to edit xhp files in the office and
>> which provides some helper to manage the id's. That is at least what I
>> remember but without guarantee.
>>
>> Hopefully the extension is available or we can find the code for it. It
>> will probably help to understand it.
>>
>> Sorry that I can't provide more help here (or should I say information)
>>
>> Juergen
>>
>>
>>  Uwe Fischer has posted on this list (12/08 and 12/09, re the
> BerkeleyDB). He should know the answers right away.
>
> My strong suspicion is that the l10n tag has to do with warning the
> translators that localization is needed.
>  /tj/
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message