Reformatting project goals and moved links to the end.

[history-fsf.git] / README.md

# FSF History page

This is a timeline project to chronicle the historical events surrounding the
Free Software Foundation.

Link to production site: https://www.fsf.org/history/

## Project description

We have a [final page](https://www.fsf.org/history/),
[source and picture files](https://www.fsf.org/history/fsf-history.tar.gz),
a markdown file, and a
[translation](https://flallemand.fr/divers/fsf-history/).

### Goals

- Generate the history page from source.
  - Generate the https://www.fsf.org/history/index.html file from our source
    file in MarkDown or JSON format using a simple scripting language
    (BASH/Python preferably). Basically this would involve creating a simple
    custom static site generator. Below is the syntax used by the source file.
    - The source is currently in ikiwiki MarkDown format, but it is not a
      traditional MarkDown document as it would need to be rendered in the way
      that the history page currently is displayed. Maybe converting the
      markdown to JSON would be a good first step.
- Internationalization (i18n)
  - Create a method to convert the history page
    https://www.fsf.org/history/index.html to various other languages. A French
    translation might be rendered to https://www.fsf.org/history/fr/index.html
    URL for example.
    - This could be converting the rendered HTML to po with html2po and then
      gettext to make new versions.
      - Example command converting HTML to a po file: `sudo apt install translate-toolkit && wget https://www.fsf.org/history/index.html && html2po index.html > messages.po`
      - <http://docs.translatehouse.org/projects/translate-toolkit/en/latest/commands/html2po.html>
    - We currently have a French translation in HTML format, but we would need
      to convert this into a reproducable format that works with whatever
      system we decide to use.
- Automatically generate new pages.
  - On the server-side, we would need a simple BASH script that is run by an
    automated cron job that fetches new changes from this repository and builds
    the pages with the new changes if necessary and creates new translations
    when available.

## Syntax

Entry syntax:

```
## TITLE
* ID: simple-unique-sublink
* MONTH: APR
* YEAR: 1985
* LINK: <https://link.to.relevant.website/>
* IMAGE:  Location of image to use
* IMAGE SHAPE: rectangle or circle
* IMAGE ALT TEXT: Single sentence that explains what the image contains for the visually impaired and search engine optimization.
* IMAGE LICENSE: Copyright 2021 Free Software Foundation, Inc. CC-BY-SA-4.0
* NOTES: Text that will be skipped by the generation.
* TEXT-BODY: Description that can be longer.
* TEXT-MORE: Read more >
```

Syntax description:

* TITLE
  - Required.
  - The title of the entry that will be displayed as a bold header.
* ID
  - Required.
  - The ID is a unique abbreviated short code that can be used to link someone
    to a historical item within the context of the rest of the page.
* MONTH
  - Optional.
  - Three letter abbreviation for the month when the event happened.
* YEAR: 1985
  - Required.
  - Four digit year when the event happened.
* LINK
  - Required.
  - The URL most related to the historical event.
* IMAGE
  - Optional.
  - Location of an image to accompany the event.
* IMAGE SHAPE
  - Required if IMAGE is used.
  - The shape of the picture.
  - Valid answers are `rectangle` or `circle` only.
  - Generally, photos are rectangles and logos are circles.
* IMAGE ALT TEXT
  - Required if IMAGE is used.
  - For accessibility, single sentence that explains what the image contains
    for the visually impaired and search engine optimization.
* IMAGE LICENSE
  - Required if IMAGE is used.
  - The license of the image.
* NOTES
  - Optional.
  - Notes that will not be generated into the production site.
* TEXT-BODY
  - Optional.
  - Description of the event.
* TEXT-MORE: Read more >
  - Optional.
  - Text for the link.  We typically just use `Read more >` for this.

## Links

Some of the reference locations are only accessible to internal staff. I tried
to mark all of those.  I might have missed pictures, but they should be linked
from the production site.

* Development link: <https://static.fsf.org/nosvn/demos/history-static/>
* Production link: <https://www.fsf.org/history/>
* The original image we are drafting from:
  common/fundraising/biannual-fundraisers/2020-fall/timeline/ (Internal
  location)
* [Member Forum post with comments](https://forum.members.fsf.org/t/fsf-history-page/3701)
* <https://rt.gnu.org/Ticket/Display.html?id=1748452> (Internal location) RT
  ticket about adding fsfe, fsff, fsfi, and fsfla logos.