Glyph - Topics

Sections can also be used to create topics. In a technical writing context, the term topic identifies a single page of an online help (e.g. a Compiled HTML file, or CHM). Topics should generally be:

  • self-contained, in the sense that they should make sense on their own, ideally without the need to be read in sequence
  • be used for either concepts, tasks or references
  • be divided into meaningful sections like Introduction, Procedure, Result

Glyph does not formally enforce the correctness of topic composition and usage, but it does enable authors to create them as a sort of external sections. Consider the following Glyph code:

1section[
2  @title[My First Topic]
3  @id[first_topic]
4  @src[test/first_topic.glyph]
5]

This is an ordinary section with a title and an explicit ID, but it has no contents. Instead, its @src attribute references an external file. If you are generating a single-file document, like a standalone HTML file or a PDF file, the code snippet above is exactly the same as the following:

1section[
2  @title[My First Topic]
3  @id[first_topic]
4  include[test/first_topic.glyph]
5]

On the other hand, if you are planning on producing a document comprised of multiple files (see Web/Web5 Output), the @src attribute tells Glyph to create a topic for the section. In this case:

  • The @title attribute must be specified and is used as the topic title
  • The body of the topic is constituted by the contents of the file referenced by the @src attribute.
  • The topic file is rendered according to a specific layout.
  • The location of the topic is the same as the location of the included file, mirrored in the output folder.
  • Glyph takes care of changing the file extensions and resolving links automatically, regardless of the output target.