Nerd needs help with HelpAuthoring extension

[bubli]

Okay folks,

at this point I'm giving up and asking for help. Apologies if those questions were asked dozen
times before, it is my first time on this list.

In the context of TDF tender work regarding generating screenshots for documentation, I'm
trying to embed some images ( = screenshots we've created ) into couple of .xhp files. I've
installed HelpAuthoring extension, but obviously I'm too nerdy to use any GUI tool for anything

1. Every time I do even a simple edit (such as, adding a word) to an .xhp file with Writer +
HelpAuthoring extension, saving messes up the file so badly that it longer displays. I see either
blank help page or default help index landing page. A quick 'git diff' shows lots of whitespace
changes, but maybe there is something else, too

What am I doing wrong? Is there something special I need to do before I save the file? (such as,
don't 'Save', but 'Save As' and choose .xhp filter) Is there some minimum version of Libreoffice
needed for this extension to work reliably?

2. Of course, I'd be the most productive, if I didn't have to use any GUI tool and if I could simply
edit those .xhp files in a text editor (that doesn't mess up)
  
But to insert a paragraph or an image, I understand those need to have some unique ids. Where
do I get those? Is there a way to generate them outside HelpAuthoring extension?

3. Is there some simple and effective way how to preview the file I've just edited? I don't
consider 'make helpcontent2 && instdir/program/soffice' and then navigating to the given help
page effective enough

[ohallot]

Hello Katarina

Okay folks,

at this point I'm giving up and asking for help. Apologies if those questions were asked dozen
times before, it is my first time on this list.

In the context of TDF tender work regarding generating screenshots for documentation, I'm
trying to embed some images ( = screenshots we've created ) into couple of .xhp files. I've
installed HelpAuthoring extension, but obviously I'm too nerdy to use any GUI tool for anything

1. Every time I do even a simple edit (such as, adding a word) to an .xhp file with Writer +
HelpAuthoring extension, saving messes up the file so badly that it longer displays. I see either
blank help page or default help index landing page. A quick 'git diff' shows lots of whitespace
changes, but maybe there is something else, too

What am I doing wrong? Is there something special I need to do before I save the file? (such as,
don't 'Save', but 'Save As' and choose .xhp filter) Is there some minimum version of Libreoffice
needed for this extension to work reliably?

The extension does help a lot but is not error-proof and has some bugs
in corner cases. I use it for bulk content insertion, basic formatting,
bookmarking and sections placeholders. At the end, it is inevitable IMHO
to go to the XML source and do some tweaks in a text editor.

On the white spaces, these are irrelevant for the page rendering. If a
blank page is the result, then there must be a DTD violation and the
XLST failed to produce a valid html.

Information on the helpcontent XML is available here:
https://wiki.documentfoundation.org/HelpContentAuthoring

2. Of course, I'd be the most productive, if I didn't have to use any GUI tool and if I could simply
edit those .xhp files in a text editor (that doesn't mess up)
  
But to insert a paragraph or an image, I understand those need to have some unique ids. Where
do I get those? Is there a way to generate them outside HelpAuthoring extension?

Put whatever you want, manually. It only has to be unique within the
file, because the parID + filename + filepath produces an unique
identifier for translation process. The parID is generated by a
pseudo-random algorithm.

Trick: if you copy&paste a paragraph, you just have to change one of the
digits of the parID, but only in a text editor.

3. Is there some simple and effective way how to preview the file I've just edited? I don't
consider 'make helpcontent2 && instdir/program/soffice' and then navigating to the given help
page effective enough

You actually can just do a make, but it is inevitable to navigate to
the help page.

You can eventually use vm173.documentfoundation.org and do the XML
editing directly. Please read
https://wiki.documentfoundation.org/OnlineHelpContent down to the last
line.

I hope this help you, poke me on IRC for further details.
regards