alan-if / alan-docs

Alan IF Documentation Project

Home Page:https://git.io/alan-docs

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Pending Glossary Entries

tajmone opened this issue · comments

This issue serves as a reminder of the Glossary status, and its pending entries — any desired new entry can be added to the list by editing this post (even if the entry placeholder is not present in the glossary source file).

The Glossary of the ALAN Manual (in file: manual_17.asciidoc) contains some commented out entries placeholders which only need to be uncommented, and their definitions written.

  • attribute
  • BNF
  • class
  • clause
  • construct
  • escaping
  • expression
  • identifier
  • inheritance
  • instance
  • property
  • stropping

Preview Links

To view the current state of the Glossary:

About the Glossary

The need for a glossary at the end of the Alan Manual has come up a number of times on the ALAN-IF Yahoo group.

We'll need a bunch of entries (and well polished definitions) to make the effort worth its time — let's say, at least 10 entries. But the work on the Glossary is already in progress, since all documentation edits are currently taking place in the dev-man branch only (and sub-branches sometimes), for the upcoming next Beta release.

The idea is to offer the reader a way to look-up any technical terms that he/she might have encountered in the course of the Manual, in order to better grasp them and be presented with some external links to learn more about the topic.

Glossaries in Asciidoctor

Asciidoctor supports Glossary in both the HTML and PDF backends.

As for the PDF backend (via DocBook → asciidoctor-fopub), it's really prickly about formatting, so extra care should be taken to ensure that the Glossary is rendered as expected in PDF — even if it might look fine in HTML, it could be completely broken in PDF!

Useful Links

Links to Online Glossaries

Some useful online glossaries on programming terminology: