incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Regina Henschel <>
Subject Re: Conventions in help files
Date Mon, 06 Feb 2012 20:02:03 GMT
Hi Uwe,

thanks for your detailed answer.

Uwe Fischer schrieb:
> Hi,
> I try to give some answers regarding Help authoring. A Google search with
> "helpauthoring" 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 ...

I have read those parts of the document, which are about the 
xml-structure. It is clear so far.

> 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.

OK. So there is no magic additional information in the numbers. That 
makes it easier.

> 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.

Line caps are in the scope of all modules, so it needs to be in shared. 
The file shared\01\05200100.xhp should be the correct place. It contains 
the other texts for that dialog page.

> 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
> 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.

Good to know. So I need not wonder about the prefix SVX:. Nevertheless, 
still using the same as the associated bookmark seems meaningful to me.

> 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.

Thanks for the warning. I indeed tend to forget, that changes in help 
will trigger a lot of translations.

> 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.

I have got it, but I could not figure out how to use it.

> 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.

I have edited it with XMLNotepad, which allows edition in the node tree 

> 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.

Then doing it in two steps makes sense, starting with the pure extended 
help tips. I'll build that part now, hoping that it works as I want.

Kind regards

View raw message