Skip to content
GitLab
Projects Groups Topics Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
  • Sign in
  • E escet
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Graph
    • Compare revisions
    • Locked files
  • Issues 101
    • Issues 101
    • List
    • Boards
    • Service Desk
    • Milestones
    • Iterations
  • Merge requests 7
    • Merge requests 7
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Artifacts
    • Schedules
    • Test cases
  • Deployments
    • Deployments
    • Releases
  • Packages and registries
    • Packages and registries
    • Model experiments
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • Eclipse ProjectsEclipse Projects
  • Eclipse ESCET (Supervisory Control Engineering Toolkit)
  • escet
  • Issues
  • #54

General documentation style/source improvements

Things to consider:

  • Styling
    • Proper/consistent use of layout macros, e.g. menu, kbd, btn.
    • Get rid of table/figure references and titles.
      • They are numbered in the single-page HTML output, and thus a bit weird if we split it and not renumber them. Also, for LaTeX that moves the figures around, references and titles make sense, but for AsciiDoc HTML/PDF output the order is as in the source file.
      • We can say things like "... as in the following figure:" and then immediately put the figure after that.
      • This mostly concerns Chi, but we should check all documentation sets.
  • Documentation source layout
    • Everywhere exactly one empty line separation, except two empty lines before new section?
    • Single sentence per source line, for simpler reviewing (less irrelevant diffs).
  • AsciiDoc features
    • Use * for unordered lists instead of -. See also #54 (comment 303258).
  • Other
    • Use https instead of http in links where relevant.
Edited Dec 06, 2021 by Ferdie Reijnen
Assignee
Assign to
Time tracking

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