[feature] Accept optional (and overridable) harness attribute(s)

[kvid]

There is a Harness.color_mode attribute that is not currently possible to specify from the YAML input file, and additional similar attributes might be needed later.

How should such an attribute be specified in the YAML input?

harness:
  color_mode: SHORT

or without a section:

color_mode: SHORT

or some other way?

What's the recommended way to allow specifying a value for such an attribute in a prepended YAML file, and optionally override the value in the main harness YAML file?

# Prepended preferences.yml file
harness: &harness_preferences
  color_mode: SHORT

# Main harness.yml file
harness:
  <<: *harness_preferences
  color_mode: HEX

or without a section:

# Prepended preferences.yml file
color_mode: SHORT

# Main harness.yml file
color_mode: HEX

or some other way?

[kvid]

• Maybe file_out and output_formats also are harness attribute candidates to obtain what is suggested in [feature] Only output the files that user requests #60 (comment)?
• input_language might be a future candidate as suggested in [feature] improved multilingual color input #135 (comment).
• title and notes/description with HTML contents (possibly including hyperlinks) might be useful for the HTML output.

[formatc1702]

There might be some more metadata fields that could fit into this section.
Especially when generating a proper technical drawing with a title block (see example from in #32 / #74), a few things come to mind:

metadata:
  title: Main power harness
  pn: 123-456-789
  authors:
    created:
      author: J. Doe
      date: 2020-01-01
    approved:
      author: X. Yz
      date: 2020-02-02
  revisions:
    01:
      description: Add ferrules
      author: J. Doe
      date: 2020-03-03
    02:
      ...
  notes: |
    This could be a multiline
    string that appears somewhere
    on the page.

I don't know if this kind of metadata about the harness should be mixed with rendering parameters such as the originally proposed color_mode, output_formats etc. but it's worth considering.

[kvid]

There might be some more metadata fields that could fit into this section.
Especially when generating a proper technical drawing with a title block (see example from in #32 / #74), a few things come to mind:

metadata:
  title: Main power harness
      ...
  notes: |
    This could be a multiline
    string that appears somewhere
    on the page.

I don't know if this kind of metadata about the harness should be mixed with rendering parameters such as the originally proposed color_mode, output_formats etc. but it's worth considering.

• Some metadata entries are useful in more than output, e.g. title, author, date and notes in both HTML and technical drawing output. Maybe all metadata can be included in both of these outputs?

• Rendering options like Harness.color_mode and Harness.mini_bom_mode (suggested in Feature/additional components #115) and other options suggested above might fit into a group called options:

metadata:
  title: Main power harness
  ...
options:
  color_mode: HEX
  mini_bom_mode: False
connectors:
  ...
cables:
  ...
connections:
  ...

[formatc1702]

• Some metadata entries are useful in more than output, e.g. title, author, date and notes in both HTML and technical drawing output. Maybe all metadata can be included in both of these outputs?

Maybe my intention wasn't so clear before. The "technical drawing output" should essentially replace/expand the current HTML output. The idea is that a user can optionally specify a HTML template that will be filled with the metadata; otherwise, a very basic HTML output (similar to now) is generated. My hope is to then easily convert the HTML to PDF, so we don't need to deal with another, completely separate PDF output generator.

• Rendering options like Harness.color_mode and Harness.mini_bom_mode (suggested in Feature/additional components #115) and other options suggested above might fit into a group called options:

Splitting metadata and options sounds good to me.
options could also include things like page-size. page-orientation, background-color and other arbitrary parameters to replace within the provided HTML template.

---

Update:
I've edited my previous comment, nesting the created and approved fields within authors.
This allows any person/company to define their own custom authorship fields, and WireViz can easily iterate over all of them, regardless of name.
I've seen documents that have up to five authors:

Designed -> Checked -> Drawn -> Approved -> QA

and this would enable using any language for these visible fields as well.

[kvid]

• IMHO, metadata.title should have a non-empty default value, and I suggest the base output filename of diagram and HTML files (i.e. without any folder part or extension) as a default title.
• I also suggest the HTML body to contain something like this:

<h1>{metadata.title}</h1>
{metadata.description}
<h2>Diagram</h2>
{file contents of {filename}.svg}
<h2>Bill of Materials</h2>
{table with BOM}
<h2>Notes</h2>
{metadata.notes}

[formatc1702]

I am closing this issue after merging #214.

The only thing still open is the overriding of options. I plan on opening a separate issue to generalize this discussion.