Documentation

Making notes of some reference materials for the XHP specification, as I start to investigate it:

• https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/2
• https://wiki.documentfoundation.org/images/e/e8/OOo2HelpAuthoring.pdf

This one may also help in the editor phase

https://wiki.documentfoundation.org/Documentation/XHP_Code_Snippets_for_KDE_Editors

So here's an update on the XML editor situation. Buovjaga has helpfully pointed out a couple of options:

• CodeMirror, which is non-WYSIWYG: https://codemirror.net
• ProseMirror, which adds WYSIWYG on top: https://prosemirror.net

I'm investigating the latter now, as I believe WYSIWYG is important for encouraging people to work on the docs, without having to know what's going on with XML in the background.

Also waiting to hear from Jean Spiteri regarding his ideas, but haven't heard from him for a few weeks now.

Florian Effenberger wrote:

Olivier Hallot and Mike Saunders - can you update this ticket? Ideally Olivier shares the state of play with Mike and outlines the next steps, and Mike updates the ticket as we've done initially. Then we can split individual larger tasks into subtickets.

I'll arrange a catch-up call with Olivier now, and we can make a roadmap for the next steps. Then I'll update this.

Just to let you know, I've finished a basic 1.0 version of my work if there is still interest. Mike Saunders and Olivier Hallot should have received a status update from me. If anyone wants to help, feel free to ask for updates on this ticket. Thank you Florian for letting me know (indirectly) about the mention feature.

Wiki page is ready and published.

https://wiki.documentfoundation.org/Documentation/GerritEditing

Mike Saunders wrote:

The formatting is missing, but I'm trying to implement that. It's a bit tricky when paragraph tags in XHP can have so many different parameters. Also, the big issue will be getting the data back out in the right format after editing. I'll do more research.

Thanks for working on this! I've sent you some details in the mail, but just for the record here - I'm currently particularly excited about another editor, codemirror, see:

http://codemirror.net/demo/xmlcomplete.html

would be great to feed that one with the xhp XML schema & see if it is completing the syntax out of the box...

So here's Kendy's proposal of things to do/check before the conference:

At the current stage, to have something concrete before the conference,
I would suggest to:

* Deploy CodeMirror on some TDF VM so that we can see it all & hack on
  it

    + http://codemirror.net/doc/manual.html

* Add there the http://codemirror.net/doc/manual.html#addon_xml-hint
  and feed it with the XML schema of the XHP files

    + to get the autocompletion of the XHP syntax
    + if it is too hard to get it fully there, let's start with just
      a subset of the XHP

* Add there the XML syntax highlighting for XHP

    + initially the stock XML syntax highlighting
    + try extending it with one thing - like that all 'Heading 1's get
      a larger font (or something in bold is displayed in bold - or
      anything like that), so that we get a feel how hard it is to
      modify the syntax highlighting to our needs

* Evaluate 

    + is it an improvement (with the above implemented) compared to any
      other way of XHP creation?
    + will it be even better if we extend the syntax highlighting and
      autocompletion with more rules?
    + can we add some buttons that will automate stuff - like initial
      template of a new help page or so?

Would be great to version control all the above steps in git, so that
it is easy to see what changes were needed in the syntax highlighting
and in the autocompletion, etc.

I can take care of these proposals as part of my proposal (if accepted) or separately (if it isn't).

Quick update: I've added snippets and more XHP schema to the editor, along with undo/redo buttons and an option to create a new XPH document with a basic structure from scratch. I've shared a short video demonstrating the latest features with Olivier and Kendy.

Next steps: finalise snippets and schema, try to modify CSS as mentioned in previous update, then deploy to a TDF VM for wider testing.

The editor is now in the Git repo and Olivier is making updates:

https://gerrit.libreoffice.org/#/c/58500/

I'll catch up with it and work on more changes after the LO 6.1 release.

Mike Saunders wrote:

Latest version of editor attached (xhp-editor-23aug.zip) with the following changes:

Cool, thank you! Great stuff :-)

Olivier - can you please merge the changes with yours, and push to the dev-tools under Mike's name?

Mike - would be great if you start using the git repo too, so that you can send the stuff as patches, or push to gerrit directly :-)

Jan Holesovsky wrote:

Mike - would be great if you start using the git repo too, so that you can send the stuff as patches, or push to gerrit directly :-)

Yep, I'm still quite new to Git so I'll read up and use it in future -- just wanted to get these latest changes to Olivier ASAP :-)

Just catching up on the editor: Olivier, did you hear anything from Guilhem about a test VM for Gerrit, to try out our new editor? He mentioned wanting to test it as a plugin first... If not, let's discuss it in the all-in call on Tuesday, when we can get the latest situation from Guilhem (I know he was busy with other infra stuff in the last couple of weeks).

The plan is to have a call between Mike, Olivier and me next week, and then update this master ticket to the status quo
Mike to schedule the meeting, tentatively after the Tuesday team call

Notes from the team meeting in Munich:

New XHP editor - https://newdesign.libreoffice.org/help_editor/index.html

• Need to change rendering in right-hand panel to PHP - to do it server-side (currently doesn't work in Safari/IE)
• For "Open File" - picker/browser would be better
• Buttons complete - make prettier
• CodeMirror plugin can be built against our version of Gerrit - but JS bits didn't work https://vm178.documentfoundation.org/#/q/status:open - "Plugin "codemirror-editor" failed to load" - it's trying to load https://vm178.documentfoundation.org/plugins/codemirror-editor/static/codemirror_editor.html
• Eventual plan to upgrade to Gerrit 2.16, which should make it work - upgrades will take a lot of work though, path is very problematic - so not before the conference; possibly before FOSDEM
• For LibOCon: finalise interface and PHP rendering, and encourage doc editors to use it in copy-and-paste mode

Quick notes from call with Olivier, Florian and Mike on 30 July

• For XHP editor tasks from comment #24, Olivier thinks he can get most of them done for LibOCon Almeria (Mike can help where appropriate, and work on cosmetic improvements)
• After that, identify what else we can deliver for FOSDEM
• Look at converting more documentation into videos
• Mike to make a SSO video (Redmine #2940) to make onboarding easier for new docs contributors

Olivier, Florian and I just had a quick meeting – Olivier will dedicate a chunk of time to finalise some parts of the new XHP editor, and Mike will work on the cosmetic side. For anything we can't implement, we will at least have the editor in a decent shape to show to the community (and hopefully get further help).

Florian Effenberger wrote:

Mike, can you update the ticket according to what we discussed in the call, if there's anything to update in the description?

What we discussed in the call was Olivier taking a dedicated week to work on the editor. The remaining steps from the description are:

• For LO 6.1, implement an "Edit" button in the online help, along with login credentials and a user-friendly WYSIWYG editor that saves as XHP
• Then implement the workflow: use Git as ultimate source of XHP, and Gerrit for submissions of help content changes. When the user saves his/her changes, the editor creates a commit after submission, which goes to Gerrit for review by the docs team. (Maybe add a bot to do XML verification before integration?)
• Long-term goal for LO 6.2: extend XHP for merging with the books (eg sections or markup) - maybe even generate new guidebooks from that content. Add an editor preview mode - eg show how changes will look in the context of other help sections or a book

Of course, 6.1 and 6.2 have already been released, and we can't implement the second step until Gerrit is updated to at least 2.16. I don't know the status of the third point there -- Olivier?

We had a new approach to the editor and is reflected in the ticket #2938.

The editor is in usable condition and is actually being used by the community.

https://newdesign.libreoffice.org/xhpeditor/index.php

Latests 6 mo activities related to documentation

- restored extended tips from Help in the user interface, coodinating with translations reuse
- Dozens of fixes in the Help contents, catching up the gap between software development and proper documentation
- Several Improvements and fixes in the New Help framework
- Coordination of the documentation team meetings and resource allocations for them, discussions on technical issues for publications
- Management and execution of the Google Seasons of Doc 2020, got 2 projects, extended help on Calc functions and e-learning for Calc
- Staff activities
- Local community activities.

Lasts year activities related to documentation

- Dozens of fixes in the Help contents, catching up the gap between software development and proper documentation
https://gerrit.libreoffice.org/q/status:merged+project:help+author:olivier.hallot%2540libreoffice.org+since:2021-05-10+before:2021-12-20

- Several Improvements and fixes in the New Help framework

- Coordination of the documentation team meetings and resource allocations for them, discussions on technical issues for publications

- Publication of LibreOffice Bookshelf
- https://books.libreoffice.org/en/
- https://books.libreoffice.org/pt-br/

- Publication of Guides in https://documentation.libreoffice.org

- Patches in core projects, mostly related to documentation
https://gerrit.libreoffice.org/q/author:olivier.hallot%2540libreoffice.org+project:core

- Staff activities

- Local community activities.
https://pt-br.blog.documentfoundation.org/