More Worg build workflow

More Worg build workflow

[Tim Cross]

apologies if these questions about worg are becoming a little tiresome -
still just trying to work out how things all work and more importantly,
what level of comfort the community has with change. i

As I'm digging more and more into understanding worg, I'm finding things
which I think need to be changed. This is not to say what has been done
is wrong, but rather that as things have developed, as technology
(including org) has improved and as user expectations have changed,
there are things we probably should adjust to bring worg forward and
keep it current. However, it is also likely some things are the way they
are for very good reasons I'm just not aware of. I'm therefore reluctant
to make any significant changes without first raising it on this list.

Based on only a few hours going through worg and Org mode's support for
generating static web content, there are 3 very broad goals I would like
to achieve 

1. Improve worg's presentation layer to 
   - Improve page responsiveness wrt different size screens
   - Improve accessibility support (fonts, colours, links, tags etc)
   - Improve page navigation. Make it easier to find specific
     information and easier to browse and explore the site. 

2. Make it easier for users to contribute new content, updates for
   existing content or provide feedback  

3. Improve the build and deployment workflow. 
   - Add the ability to deploy to a dev/uat site. Reduce unexpected
     impact to production site and increase confidence when making
     changes or adding new content. 
   - Allow anyone to easily clone the worg repository and bring up a
     working site locally for development, testing and experimentation
     etc.

Today I have been going through what is required in order to deploy a
copy of the worg site locally so that I have something to work with
while looking at points 1 and 2. This has been slightly harder than I
think it should be. Some of the issues are due to hard coded paths and
URLs scattered through the source files, conflicts with my local Emacs
and org settings and possibly some version issues (not sure yet). 

Some of these issues seem to be related to the very simple build
workflow being used. The worg site is not using the org publish
functionality - while it sort of does the same thing, it really is just
a recursive call to org-html-export-to-html for all files with a *.org
extension. While org publish does pretty much the same thing, it does
have some 'sugar' which can make the process a little more flexible and
provides a consistent way to apply settings consistently across the
whole project. 

As a simple example. Each org file has an org-html-link-home settings
which is https://orgmode.org/worg/. We really don't want that link hard
coded in every *.org file. Would be far better if that link is added as
part of the publishing process as we could then change it depending on
the environment we are deploying to. Removing things like this from the
individual org files also means things are easier for new contributors
as they don't need to worry about adding such values. 

What I'm thinking and wanted feedback on is

1. Update the build process to be based on org publish by defining an
   org-publish-project-alist variable. 
2. Moving as many 'global' and/or static settings to be managed within
   the org-publish-project-alist properties and removing them from each
   individual org file.

These changes will likely also require re-arrangement of file and
directory layout within the git repository to better meet the updated
publishing workflow requirements. 

Finally, as this is likely to be a sizeable piece of work, can anyone
tell me if the FSF copyright assignment process comes into play? I know
this is the case with org changes, but I'm hoping it isn't with worg as
I have other constraints which prevent me from signing such an
agreement. 

Re: More Worg build workflow

[Ihor Radchenko]

Tim Cross <theophilusx@gmail.com> writes:

> Based on only a few hours going through worg and Org mode's support for
> generating static web content, there are 3 very broad goals I would like
> to achieve 
>
> 1. Improve worg's presentation layer to 
> ...
> 2. Make it easier for users to contribute new content, updates for
>    existing content or provide feedback  
> 
> 3. Improve the build and deployment workflow. 
> ...

Sounds good.

> What I'm thinking and wanted feedback on is
>
> 1. Update the build process to be based on org publish by defining an
>    org-publish-project-alist variable.

This does make sense.

> 2. Moving as many 'global' and/or static settings to be managed within
>    the org-publish-project-alist properties and removing them from each
>    individual org file.

Also makes sense.

> Finally, as this is likely to be a sizeable piece of work, can anyone
> tell me if the FSF copyright assignment process comes into play? I know
> this is the case with org changes, but I'm hoping it isn't with worg as
> I have other constraints which prevent me from signing such an
> agreement. 

No, AFAIK. WORG is supposed to be more lax licence-wise.

I am CCing Bastien in case if there are any cavears I am not aware
about.

Best,
Ihor