[sane-devel] [janitorial] post 1.0.28

[Olaf Meeuwissen]

Hi Povilas,

Povilas Kanapickas writes:

> Hi Olaf,
>
> On 8/7/19 4:26 PM, Olaf Meeuwissen wrote:
>> # Updating the HTML version of the manual pages requires a tool from a
>> # site that no longer exists ... :-/
>> # I've been looking at using something else but with nothing so far that
>> # produces something acceptable.
>
> Are we talking about http://sane-project.org/html/ or everything under
> http://sane-project.org/docs.html? I may be able to help.

We're talking everything under https://sane-project.org/man/.  The files
there can be found in the website project, see

  https://gitlab.com/sane-project/website/tree/master/man/

Poking into the logs for that, I noticed that Allan has dutifully
updated this after every release and that I have been making minor
corrections to those pages as well.  I'm afraid some of those will
need to be redone for re-generated pages :-(

@Allan> Could you re-generate these pages on a separate branch and push
        that?  I'll be "happy" to re-apply any corrections.

>> [...] Markdown for files in git would improve rendering in the GiLab
>> web interface but GNU standards have their own ideas about filenames.
>> Perhaps that some build tweak can bridge that divide.
>
> I wonder if we could just append .md to the GNU filenames and then
> suppress any warnings resulting from that.

Actually, I was thinking along the line of renaming in the repository
and tell make to create any files that are needed for the source tarball
by copying the corresponding *.md file :-)

  %: %.md
  	cp $< $@

Hmm, % rules are a GNU extension and autogen.sh already complains about
those.  Anyway, I'll have a look and see.

>> For the website, using one of the many static site generators could make
>> the site look more current as well as more maintainable.  Nobody really
>> likes plain HTML, I think.  That said, it's not just the looks, much of
>> the information is also badly dated.
>
> Agreed. I think the focus should be on updating the outdated information
> though. Looking in plain html is nothing until you see the last status
> update was 10 years ago.

I was wondering whether rewriting the website from scratch would be a
good idea.  Start with an outline, then put some "flesh" on it by
referring to the existing site.  The rewrite can live next to the
current site until we're happy with switching over.

How does that sound?

BTW, given the comment below, I was thinking about using Sphinx for the
website's rewrite.

>> Concerning the SANE API specification, I've been thinking of ripping it
>> out of the sane-backends code and convert it for use with Sphinx, even
>> setting up integration with readthedocs.io so the API spec would be
>> available in a versioned fashion as well as a "current" version on our
>> website.
>
> Agreed.

Thanks for thinking along,
--
Olaf Meeuwissen, LPIC-2            FSF Associate Member since 2004-01-27
 GnuPG key: F84A2DD9/B3C0 2F47 EA19 64F4 9F13  F43E B8A4 A88A F84A 2DD9
 Support Free Software                        https://my.fsf.org/donate
 Join the Free Software Foundation              https://my.fsf.org/join