Move help for editors to help-en and help-common namespaces

[RogerHaase]

For wiki editors, the sample docs are probably of more use than the .rst docs created for primarily for developers and wiki admins.

One way to provide the sample docs to a wiki instance is to create a means of loading them to a separate namespace. This would provide documentation similar to the moin 1.9 underlay directory.

An added advantage of doing this is that wiki admins could use the docs namespace to document local mods such as macros, templates, etc.

There are no local docs included with test.pypi packaging. Adding a means of loading the sample docs to a namespace is a possible solution..

[UlrichB22]

I would like to have the examples and the help separated. Maybe you can also include the language in the namespace name. Then it is easier to have English and local language help texts in the same wiki.

[RogerHaase]

By examples and help separated, you mean image/audio/video in /docs/ and markup text in /docs-en/?

On Sun, Mar 13, 2022 at 12:30 PM UlrichB22 @.***> wrote:

I would like to have the examples and the help separated. Maybe you can also include the language in the namespace name. Then it is easier to have English and local language help texts in the same wiki.

— Reply to this email directly, view it on GitHub https://github.com/moinwiki/moin/issues/1155#issuecomment-1066166771, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGODHUQQSJXCMZDUX72HTDU7Y63NANCNFSM5JUYKWDA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you authored the thread.Message ID: @.***>

[RogerHaase]

To Do:

1. create a new directory /moin/src/moin/docs/ to hold multiple language doc files in moin backup format
2. modify wikiconfig to define namespaces for docs and docs-en
3. split current sample items into docs (media) and docs-en (text markup) namespaces
4. fix broken links caused by split of items into separate namespaces
5. create backups of docs and docs-en namespaces in /moin/src/moin/docs/ named docs.moin and docs-en.moin
6. add load-docs --lang en command to load docs and docs-en namespaces
7. change Click for help... link on +modify to load help based on user's locale
8. update *.rst docs on how to create/install translations for wiki editors
9. remove contrib/sample-backup.moin and load-sample command

Suggestions?

[UlrichB22]

I essentially support your plan. Here are some additional suggestions:

a. Help content should be under version control on a per-page basis. We can use Github or a Moin2 wiki to maintain the pages. Working with backups in git is not optimal.

b. For users I would prefer the name "help" instead of "docs".

c. sample-docs is a sandbox for developer and admins for testing. IMO the old help content https://moinmo.in/HelpContents is a better basis for creating a new user help system. It is clearly structured, starting with a short overview and links for users, admins and a global help index.

d. There should be a fallback to the default English help content if the local language translation is ever not available.

We will support you in migrating and creating the user help content. The admin help in https://moin-20.readthedocs.io/en/latest/ is fine.

[RogerHaase]

Revised changes:

1. modify wikiconfig.py to define namespaces for help-en and help-common
2. create a new directory /moin/src/moin/help/* to hold multiple language help files in .data/.meta pairs
3. split current sample items into common (media) and en (text markup) namespaces
4. fix broken links caused by split of sample items into two namespaces
5. create version controlled copies of help-common and help-en namespaces in /moin/src/moin/help/common and /moin/src/moin/help/en
6. add load-help --namespace en command to load help-common and help-en namespaces
7. update *.rst docs on how to create/install translations for wiki editors

Next todo:

1. change Click for help... link on +modify to load help based on user's locale, default to en

Consider removing contrib/sample-backup.moin and load-sample command

[RogerHaase]

After pulling this patch to an existing clone, wiki admins must copy new ACL definitions to wikiconfig.py:

Replace:

    userprofiles_acl=dict(before='All:',
                          default='',
                          after='',
                          hierarchic=False, ),

with:

    userprofiles_acl=dict(before='All:',
                          default='',
                          after='',
                          hierarchic=False, ),
    help_common_acl=dict(before='',
                         default='All:read,write,create,destroy',
                         after='',
                         hierarchic=False, ),
    help_en_acl=dict(before='',
                     default='All:read,write,create,destroy',
                     after='',
                     hierarchic=False, ),

In the wiki instance, add new directories

help-common
    data
    meta
help-en
    data
    meta

as siblings to /wiki/data/default/

To load help files:

moin load-help -n en
moin load-help -n common

[RogerHaase]

To add editor help for another language, the namespaces, backends, and acls variables in wikiconfig.py musted be updated.

For the de locale, add this to namespaces:

'help-de': 'help-de', 

to backends:

'help-de': None,

to acls:

    'help-de': dict(before='SuperUser:read,write,create,destroy,admin',
                    default='All:read,write,create,destroy',
                    after='',
                    hierarchic=False, ),

1. stop the server
2. If a useful wiki is being used, take a backup: ./m backup
3. Delete the existing wiki: ./m del-wiki
4. Update wikicong.py as described above and save
5. Restore the backup: ./m restore
6. start the server
7. Using a browser, go to Navigation > User and click on the help-de link
8. create a home item if desired, then create items for moin, markdown, rst, docbook, creole, and mediawiki

When a user sets his User Settings > Personal > Locale to deutsch then the help links on +modify/xxx items will link to the help-de/moin item.

To add de help items to version control, create a de directory within /moin/src/moin/help. Then run:

moin dump-help -n de

[UlrichB22]

There is a small cosmetic issue with the wikiname in metadata of the loaded help items. When running moin load-help -n en after applying a customized interwikiname in wikiconfig.py, the wikiname in the metadata results in "MyMoinMoin" as stored in e.g. src/moin/help/en/Home.meta and not the customized interwikiname.

This can be fixed by adding WIKINAME to the to_kill list in https://github.com/moinwiki/moin/blob/70e86a0c07f5ebcaad5c1b893ef14c3fbef1bc8e/src/moin/scripts/maint/modify_item.py#L75

Maybe it is a good idea to delete the wikiname before saving the item. Kind request for advice.

[RogerHaase]

OK to add the fix.

Not sure about deleting the wikiname on save. A guess is that wikiname exists to support a future wiki farms feature. Wikiname was in meta data before I started contributing to moin2.

[RogerHaase]

Nothing left to do here.