One of the primary differences between the distros (variations) of your documentation sets is that some may include topics or even whole groups of topics that others don’t. For example, if your documentation set was all about an airplane, you might want to write everything about flying and repairing the airplane in a single repo. But when you publish your docs, you might want to publish the repair-related topics as one distro and the flying-related topics as another.
AsciiBinder supports this by enabling you to "distro tag" topics and topic groups within your topic map file through the use of the
Distros: setting. The distro tags that you use for this purpose are defined in your distro map file.
As an example, continuing the airplane documentation analogy, assume your
_distro_map.yml file looks like this:
_distro_map.yml file extract
name: Flymaster 9000 Piloting Guide
name: Flymaster 9000 Repair Guide
piloting-guide distro key, which we’ll use to denote flying-related content
repair-guide distro key, which we’ll use to denote repair-related content
Then your topic map file may look like this:
Name: The Flymaster 9000
- Name: Welcome
- Name: What is an Airplane?
Name: Airplane Concepts
- Name: Passenger Compartment
- Name: Engine Compartment
Distros: repair-guide (1)
- Name: Cockpit
Name: Air Navigation
Distros: piloting-guide (2)
- Name: Calculating Ground Speed
- Name: Using a Compass
||This topic-level distro tag ensures that the "Engine Compartment" topic will only appear in the "Repair Guide" distro.
||This topic-group-level distro tag ensures that the "Air Navigation" topic group will only appear in the "Piloting Guide distro.
When a topic or a topic group excludes the
Distros: setting, this is the same as saying
Distros: all. The "all" value is a reserved keyword meaning "valid for every defined distro".
Distros: setting also supports a comma delimited list of values:
AsciiBinder also supports the use of wildcards in distro keys inside of the topic map file. For instance, per our airplane example, this entry would be automatically expanded to
Distro keys can also be used to conditionalize content inside of individual topic files; this is discussed in detail in the Writer’s Guide.