Skip to content

GitLab

  • Menu
Projects Groups Snippets
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
  • Sign in
  • E escet
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 76
    • Issues 76
    • List
    • Boards
    • Service Desk
    • Milestones
    • Iterations
  • Merge requests 3
    • Merge requests 3
  • Deployments
    • Deployments
    • Releases
  • Activity
  • Graph
  • Create a new issue
  • Commits
  • Issue Boards
Collapse sidebar
  • Eclipse Projects
  • Eclipse ESCET (Supervisory Control Engineering Toolkit)
  • escet
  • Issues
  • #38

Closed
Open
Created Apr 10, 2021 by Dennis Hendriks@ddennisMaintainer

Improve AsciiDoc-generated documentation HTML style

We want to improve the HTML style of the HTML files generated by AsciiDoc. Consider the following:

  • Enable syntax highlighting, including for our own Eclipse ESCET languages.
  • Compare styling to old Sphinx/RST HTML styling.
  • Switch to sans serif font. Ensure the chosen font makes it easy to distinguish l/1, 0/O, etc. Eclipse officially uses Libre Franklin as website font, see https://www.eclipse.org/legal/documents/eclipse_foundation_branding_guidelines.pdf
  • Literal text in tables doesn't have a gray background as outside tables.
  • Hover over code block shows e.g. 'CHI' in capitals (HTML output).
  • No section anchor links in HTML output, even though enabled.
  • Let PDF renderer or browser decide table column widths, not generator.
    • Ideas: custom width or [%autowidth.stretch] or [%autowidth] for tables (not recognized by docbook converter)
  • Decide whether we like the large vertical spacing between lines, especially for code blocks.
  • Don't wrap code blocks, for HTML (do wrap inline literal text)
  • Use slightly darker code block background to make it pop out a bit more.
  • Link style in general could be improved.
  • Distinguish internal vs external links.
  • Justify text.
  • Improve table style.
  • Improve menu/btn/kbd style.
  • Syntax coloring Chi, CIF, SeText, ToolDef, console, SVG, BNF, etc.
  • Currently no styling for 'h7' to 'h9' tags (we have no h10)
    • Only 'h1' through 'h6' are official HTML and have styling.
    • Not needed if we do multi-HTML output first.
  • Enable PDF section numbers for all sections, even though not in the TOC (for all levels).
  • Improve TOC styling (indentation doesn't make it very clear, especially with longer and wrapping section names).
  • Ensure that for longer TOCs and with mulit-html page output (see #36 (closed)) the TOC scrolls to the currently visible HTML page. And maybe even to the correct section.
  • Maybe use styles that match the colors for the home/landing pages, where we use different colors for the Eclipse ESCET project, Chi, CIF, and ToolDef.

Some inspiration can be obtained here:

  • https://cstweb.wtb.tue.nl/4tc00/index.html
  • https://cstweb.wtb.tue.nl/cif/trunk-r9682/lang/tut/index.html

This may be affected by the multi-page HTML output changes (#36 (closed)), so we may want to address that first.

Edited Oct 24, 2021 by Dennis Hendriks
Assignee
Assign to
Time tracking

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent