BoostLook

This is a set of stylesheets, templates, and code for Asciidoctor and Antora rendered documentation to give it a uniform look and feel befitting the quality of Boost.

Example of integration into a doc Jamfile:

html mp11.html : mp11.adoc
    :   <use>/boost/boostlook//boostlook
        <dependency>mp11-docinfo-footer.html
    ;

Noto font files are covered under the Open Font License:

https://fonts.google.com/noto/use

Live Preview for AsciiDoc Documentation

BoostLook includes a live preview feature to streamline local development and review of AsciiDoc documentation. This allows for automatic rendering and real-time browser preview of changes made to specimen.adoc and boostlook.css files.

Overview

The preview functionality is handled by a Ruby script (boostlook_preview.rb). This script monitors AsciiDoc, HTML, and CSS files for changes, automatically rebuilding and opening the rendered HTML in your default web browser.

---

Prerequisites

Ensure the following dependencies are installed:

• Ruby (>= 2.7 recommended)
• Asciidoctor – Install via gem install asciidoctor
• Listen Gem – Install via gem install listen
• Boost.Build (b2) – Required for builds invoked by the script. Ensure it is installed and available in your system's PATH.

---

Usage and Detailed Steps

1. Install Ruby and Required Gems:

   • Ensure Ruby is installed on your system. You can check by running:

     ruby -v
     

     If Ruby is not installed, follow the instructions on ruby-lang.org to install it.
   • Install Asciidoctor:

     gem install asciidoctor
     

   • Install the Listen gem:

     gem install listen
     

2. Install Boost.Build (b2):

   • Follow the instructions on the Boost.Build website to install b2.
   • Ensure b2 is available in your system's PATH by running:

     which b2
     

3. Locate Specimen AsciiDoc File:

   • Place your AsciiDoc files in the doc directory. The default file is doc/specimen.adoc.
   • The default file structure should include:

    /boostlook
      ├── doc
      │   └── specimen.adoc <--
      │   └── ...
      ├── boostlook.css
      └── boostlook_preview.rb
      └── boostlook.rb
      └── ...
   

4. Navigate to the project directory:

   cd /path/to/boostlook
   

5. Run the preview script:

   • Ensure you're in the root folder

   ruby boostlook_preview.rb
   

6. Edit and Preview:

   • Edit your AsciiDoc (specimen.adoc) or CSS (boostlook.css) files.
   • The script will automatically detect changes and rebuild the documentation.
   • Refresh the browser to see changes.

7. Refresh Your Browser to view changes.

---

Troubleshooting

• Script Not Running:

  • Ensure all prerequisites are installed correctly.
  • Check for any error messages in the terminal and resolve them accordingly.

• Changes Not Reflecting:

  • Ensure the files being edited are within the monitored directories (doc and root directory).
  • Verify that the browser is refreshing automatically or manually refresh the browser.

• Boost.Build (b2) Not Found:

  • Ensure b2 is installed and available in your system's PATH.
  • Run which b2 to verify its availability.