Best way to create new help entries

iplaw67 · November 17, 2011, 10:53am

Hi all,

I have an itch to scratch in the Base help (which I find totally
lacking, but hey, just my opinion) and so I've been thinking about the
best way to improve it :

(1) hack the XHP files directly and then git diff them ;
- how would I deal with new entries ? my understanding is that I need to
create a new unique id somewhere ?

(2) add pages to, or expand on, the wiki online help in the hope that
these then get converted back to XHP files
- I see in the code repo that there are some python scripts for doing
this, but are they actually used ?

On a more general note, could we not move the Base help out of /shared
into its own module, like the other main modules ?

Alex

timar · November 17, 2011, 11:05am

Hi,

Hi all,

I have an itch to scratch in the Base help (which I find totally
lacking, but hey, just my opinion) and so I've been thinking about the
best way to improve it :

(1) hack the XHP files directly and then git diff them ;
- how would I deal with new entries ? my understanding is that I need to
create a new unique id somewhere ?

That would work. It's not that hard to create new unique IDs. When you
edit XHP files, you'll see where and how to use IDs. You can't do it
wrong, because if you do, the build will break. So you'll notice.

(2) add pages to, or expand on, the wiki online help in the hope that
these then get converted back to XHP files
- I see in the code repo that there are some python scripts for doing
this, but are they actually used ?

Scripts do XHP -> Wiki conversion, not the other direction. At the
moment the only way to extend the help is to modify XHP files.

On a more general note, could we not move the Base help out of /shared
into its own module, like the other main modules ?

That would be a big work at the source level and for end users the
result will be the same. Why should we bother?

Thanks,
Andras

iplaw67 · November 17, 2011, 12:03pm

Hi Andras,

That would work. It's not that hard to create new unique IDs. When you
edit XHP files, you'll see where and how to use IDs. You can't do it
wrong, because if you do, the build will break. So you'll notice.

Ah, good point :-)))

Scripts do XHP -> Wiki conversion, not the other direction. At the
moment the only way to extend the help is to modify XHP files.

Oh, ok, that's what I thought I would do anyway, so no big loss, just a
bit more painful to edit XML than a wiki page.

On a more general note, could we not move the Base help out of /shared
into its own module, like the other main modules ?

That would be a big work at the source level and for end users the
result will be the same. Why should we bother?

Purely personal motivations, because it took me ages to actually find
the database stuff - I ended up having to grep it because simple
browsing of the directory structure and looking in shared was not
exactly intuitive...and it is after all a module like the others in its
own right. Now, that I know where it is, I can live with it, but as a
barrier for first time contributors, the logical place to look would be
in its own folder alongside the other modules.

Alex

Olivier_Hallot · November 19, 2011, 9:08pm

Hi Andras

Hi,

Hi all,

I have an itch to scratch in the Base help (which I find totally
lacking, but hey, just my opinion) and so I've been thinking about the
best way to improve it :

(1) hack the XHP files directly and then git diff them ;
- how would I deal with new entries ? my understanding is that I need to
create a new unique id somewhere ?

That would work. It's not that hard to create new unique IDs. When you
edit XHP files, you'll see where and how to use IDs. You can't do it
wrong, because if you do, the build will break. So you'll notice.

I am trying to add new content in the Math help, and I know alreay where to hack. But I am lost in the following example

<table id="tbl_id3155359">
<tablerow>
<tablecell colspan="" rowspan="">
<paragraph role="paragraph" id="par_idN10563" xml-lang="en-US" l10n="F">
<image id="img_id3148697" src="starmath/res/bi21326.png" width="0.847cm" height="0.847cm"><alt id="alt_id3148697" xml-lang="en-US">Icon</alt>
</image></paragraph>
<bookmark xml-lang="en-US" branch="hid/STARMATH_HID_SMA_DRARROW" id="bm_id3150844" localize="false"/>
</tablecell>
<tablecell colspan="" rowspan="">
<paragraph role="tablehead" id="par_id3150853" xml-lang="en-US" l10n="U" oldref="88">double arrow pointing right</paragraph>
<paragraph role="paragraph" id="par_id3150866" xml-lang="en-US" l10n="U" oldref="87"><ahelp hid="HID_SMA_DRARROW">Inserts the logical operator <emph>arrow with double bar pointing right</emph> with two placeholders.</ahelp> You can also type <emph>drarrow</emph> in the <emph>Commands</emph> window.</paragraph>
</tablecell>
</tablerow>
</table>

The id's I have no references are

Where these id's are generated and what should I do to get id suitable for a new table entry as this above?

Is there a tool to edit or add new help entries?

Thanks

timar · November 19, 2011, 9:20pm

Hi Olivier,

Hi Andras

Hi,

Hi all,

I have an itch to scratch in the Base help (which I find totally
lacking, but hey, just my opinion) and so I've been thinking about the
best way to improve it :

(1) hack the XHP files directly and then git diff them ;
- how would I deal with new entries ? my understanding is that I need to
create a new unique id somewhere ?

That would work. It's not that hard to create new unique IDs. When you
edit XHP files, you'll see where and how to use IDs. You can't do it
wrong, because if you do, the build will break. So you'll notice.

I am trying to add new content in the Math help, and I know alreay where to
hack. But I am lost in the following example

<table id="tbl_id3155359">
<tablerow>
<tablecell colspan="" rowspan="">
<paragraph role="paragraph" id="par_idN10563" xml-lang="en-US" l10n="F">
<image id="img_id3148697" src="starmath/res/bi21326.png" width="0.847cm"
height="0.847cm"><alt id="alt_id3148697" xml-lang="en-US">Icon</alt>
</image></paragraph>
<bookmark xml-lang="en-US" branch="hid/STARMATH_HID_SMA_DRARROW"
id="bm_id3150844" localize="false"/>
</tablecell>
<tablecell colspan="" rowspan="">
<paragraph role="tablehead" id="par_id3150853" xml-lang="en-US" l10n="U"
oldref="88">double arrow pointing right</paragraph>
<paragraph role="paragraph" id="par_id3150866" xml-lang="en-US" l10n="U"
oldref="87"><ahelp hid="HID_SMA_DRARROW">Inserts the logical operator
<emph>arrow with double bar pointing right</emph> with two
placeholders.</ahelp> You can also type <emph>drarrow</emph> in the
<emph>Commands</emph> window.</paragraph>
</tablecell>
</tablerow>
</table>

The id's I have no references are

<table id="tbl_id3155359">
<paragraph role="paragraph" id="par_idN10563"... and the other paragraphs...
<bookmark xml-lang="en-US" branch="hid/STARMATH_HID_SMA_DRARROW"
id="bm_id3150844" localize="false"/>

Where these id's are generated and what should I do to get id suitable for a
new table entry as this above?

You can choose an arbitrary ID, it does not really matter. For example
tbl_id4155359, providing that it is unique in the file.

Is there a tool to edit or add new help entries?

At Sun/Oracle help was edited with OpenOffice.org 1.1 using a special
filter and a macro set. I don't think it is worth the effort to use
that.

Best regards,
Andras

Olivier_Hallot · November 19, 2011, 9:31pm

Hi Andras

The id's I have no references are

<table id="tbl_id3155359">
<paragraph role="paragraph" id="par_idN10563"... and the other paragraphs...
<bookmark xml-lang="en-US" branch="hid/STARMATH_HID_SMA_DRARROW"
id="bm_id3150844" localize="false"/>

Where these id's are generated and what should I do to get id suitable for a
new table entry as this above?
You can choose an arbitrary ID, it does not really matter. For example
tbl_id4155359, providing that it is unique in the file.

Thanks.. if the scope is the file, then it is really easy...

Is there a tool to edit or add new help entries?

At Sun/Oracle help was edited with OpenOffice.org 1.1 using a special
filter and a macro set. I don't think it is worth the effort to use
that.

In that particular, I am sceptic to hack xhp files with vim editor for a long text or a new feature whose help is demanded.

Can you point me to the mentioned ageing tool?

Thank you

timar · November 19, 2011, 9:53pm

Hi Olivier,

At Sun/Oracle help was edited with OpenOffice.org 1.1 using a special
filter and a macro set. I don't think it is worth the effort to use
that.

In that particular, I am sceptic to hack xhp files with vim editor for a
long text or a new feature whose help is demanded.

Can you point me to the mentioned ageing tool?

Full documentation of help format and the tool is here:
http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

I could not find the tool itself in source code of recent versions of
OOo. Also, it is not in the repository. Maybe you can find it in the
source of OOo 1.1.

Best regards,
Andras

fyva · November 19, 2011, 11:16pm

19.11.2011 17:52, Andras Timar пишет:

Hi Olivier,

At Sun/Oracle help was edited with OpenOffice.org 1.1 using a special
filter and a macro set. I don't think it is worth the effort to use
that.

In that particular, I am sceptic to hack xhp files with vim editor for a
long text or a new feature whose help is demanded.

Can you point me to the mentioned ageing tool?

Full documentation of help format and the tool is here:
http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

I could not find the tool itself in source code of recent versions of
OOo. Also, it is not in the repository. Maybe you can find it in the
source of OOo 1.1.

Best regards,
Andras

There is Extension Compiler. With it you can create xhp files directly in Writer. See http://wiki.services.openoffice.org/wiki/Extensions_Packager#Extension_Compiler .

There is also midiawiki to xhp converter by hanya (mwxhp). It is in Japanese, but the documentation in english included inside archive: http://hermione.s41.xrea.com/pukiwiki/index.php?Extensions%2Fmwxhp

There was also an extension for OpenOffice.org 1.1: helpauthoring2.oxt (here: http://ubuntuone.com/5sAd4EnOhhdPiJvhxLHpIb ).

fyva · November 20, 2011, 10:31am

19.11.2011 19:16, Clio пишет:

There is also midiawiki to xhp converter by hanya (mwxhp). It is in Japanese, but the documentation in english included inside archive: http://hermione.s41.xrea.com/pukiwiki/index.php?Extensions%2Fmwxhp

Sorry, here is the page in English where you can download mwxhp: http://hermione.s41.xrea.com/pukiwiki/index.php?OOobbs3%2F15

Olivier_Hallot · November 20, 2011, 10:42am

Thank you indeed for the useful links.

Kind regards

iplaw67 · November 20, 2011, 10:51am

Hi Andras,

Full documentation of help format and the tool is here:
http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

This document references the helpauthoring subdirectory, but such a directory is nowhere to be found in our own repo.

Is there any particular reason for this ?

I can see it in the AOOo SVN tree, does that mean that I would have to pull it from there ?

Can we not integrate it into our own tree (licensing issues) ?

Alex

timar · November 20, 2011, 11:21am

Hi Alex,

Hi Andras,

Full documentation of help format and the tool is here:
http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

This document references the helpauthoring subdirectory, but such a
directory is nowhere to be found in our own repo.

Is there any particular reason for this ?

I can see it in the AOOo SVN tree, does that mean that I would have to pull
it from there ?

Can we not integrate it into our own tree (licensing issues) ?

I did not know that there was an extension for help authoring. It is
good news, because this extension seems to be useable with
OpenOffice.org 3.0 and above, so maybe it works with LibreOffice, too.
AFAIK currently we don't take anything from AOOo SVN but it is not
forbidden to download and try this extension. I installed it but after
spending 5 minutes I could not figure out how it is supposed to be
working. Maybe it has not been finished or I am lame, Please let me
know, if you know how it works.

Thanks,
Andras