Saving this spot for discussion of the documentation overhaul.
Desiderata for me is to place documentation inside sxmo-utils repository itself so that we can require submitted patches to also include updates to the documentation in order for us to accept them. This will save the time it takes to go back over the documentation each release and "remember" what needs changed and what doesn't.
A minimal proposal is to simply move USERGUIDE.md, SYSTEMGUIDE.md, and everything else currently in sxmo-docs into a "docs" subfolder in sxmo-utils.
A more ambitious proposal would be to convert everything to scdoc and manpages (perhaps with an option to "export" these to html or md files). This would require us to rethink how we do documentation. For instance, some questions would be:
(1) Do we put the information in USERGUIDE.md and SYSTEMGUIDE.md into a "7th" level manpage?
(2) Do we want manpages for each shell script, or only major ones?
Im pro switching to scdoc for the following reasons:
- branching on man.sr.ht is a pain
- Having local-offline docs is good for a phone
However, there are some cons to consider:
- how would we add images?
- What if we make a mistake in the docs for a specific version. How would we update? Do we want a separate sxmo-docs package for this case?
Con 2 is much less likely since our docs dont get alot of changes now. However, if we rewrite the docs, con 2 is a problem
I'm also in favor of scdoc. And I think it wouldn't be that hard to inter-reference man pages so that it is easy to browse them.
Section 1 for some scripts and hooks. Section 7 for how sxmo works, in a more global way.
Ex: man 1 sxmo_autosuspend.sh would reference man 7 sxmo.suspension, which would also reference man 7 sxmo.state, which could reference the three state hooks, as man 1 sxmo_hook_screenoff.sh
We should also add man pages for related projects. I already did for sxmobar yersterday. We should do so for lisgd, wvkbd, svkbd.
And we should not forget sxmo device profile files.
About exporting them to a html website: I would say it doesn't cost much to to so. Building them and sending them to a pages.sr.ht is cheap. But I'm not sure if this should stay a complement for the wiki we have, or if this could replace it entirely.
I asked #sr.ht if source hut could build and view scdoc by itself but it seems to be a nogo. Now I'm investigating why they are rendered that badly on the webui. At least their highlighted web view could be fixed.
Ok I started in on this. Here are some thoughts.
We have a sxmo(7) man page which contains basically what USERGUIDE.md contains currently.
In sxmo(7) I refer to some pieces of sxmo that I think should have their own man pages:
o sxmo_rtcwake(1) - explains the cron features (i.e., sxmo_rtcwake.sh and sxmo_wm.sh exec)
o sxmo_contacts(1) - explains sxmo_contacts.sh
o sxmo_files(1) - explains sxmo_files.sh
o sxmo_migrate(1) - explains sxmo_migrate.sh
o sxmo_daemons(1) - ditto
o sxmo_notifications(1) - explains sxmo_notificationwrite.sh, sxmo_notificationsmenu.sh, and sxmo_notificationmonitor.sh.
o sxmo_appmenu(1) - explains the menu'ing system in detail
- I was going to have a dedicated man page for each hook, but found that our hooks are small enough, this would be doubling our work. So for references to hooks, I think we just tell users to see the hook and then make sure we document each hook in the heading in comments. Another option is to document in the hook and then write a script to scrape that document into a man page. I just think this might be tedious.
also note that I updated to reference to include ".sh"
ex: from sxmo_migrate(1) to sxmo_migrate.sh(1)
- I was going to have a dedicated man page for each hook, but found that our hooks are small enough, this would be doubling our work. So for references to hooks, I think we just tell users to see the hook and then make sure we document each hook in the heading in comments. Another option is to document in the hook and then write a script to scrape that document into a man page. I just think this might be tedious.
I don't see what could "double our works". Those man page will just have NAME, SYNOPSIS, DESCRIPTION, SEE ALSO sxmo_hooks(7). They will be very simple to write
Also, related to the hook manpages: at the top of each hook include a line that tells us which section of sxmo(7) the hook is addressed in, e.g.,
#See also man 7 sxmo.states
at the top of sxmo_hook_lock.sh