External documents (HTML, PDF, DOCX, ...)

[rosensymmetri]

Requirement projects often interface with external documents (PDF, HTML, DOCX). It is desirable to be able to navigate to such documents from the same area that you are viewing your "internal" requirements. References to external documents are important.

I was wondering what you think about supporting external documents? What I have in mind for my immediate use case is to be able to add them to the strictdoc project and to open them from the index view and the table of contents pane.

[rosensymmetri]

To be clear, I am not asking for strictdoc maintainers to implement this feature, I am just curious about whether there are any thoughts on how Strictdoc projects should integrate with external documents.

[stanislaw]

Hi @rosensymmetri,

thanks for asking this. There are several thoughts but nothing on the roadmap so far.

Here are some bullet points to give you an idea.

• Do just want to have these external documents listed on the Index view and the TOC? How should the opening work? Just letting a whatever system app responsible for a format open the document?

• Do you also want to be able to refer to an external document from a requirement? Previously, one user suggested a special requirement link/relation type, let's call it External link. With this relation, it would be possible to refer to an URL of a given standard document, for example. To synthesize this earlier user feedback with your suggestion, I could imagine that two relation types would be needed: External document (your use case) and External link (just point to a URL, external to a project tree).

• How should the document finding work? Do you want to hard-code a list of these external documents somewhere in the project config, or StrictDoc should auto-discover everything that has *.doc, *.rst, *.html in an input folder, just like it does it for *.sdoc?

• There are some thoughts on making StrictDoc support SPDX format. There is a smaller work package of making StrictDoc generate SPDX files that could be consumed by another SPDX-capable tool that would also integrate all other non-SDoc project artifacts, such as source files, licenses, third-party components, etc. A larger work package for StrictDoc would be to become an SPDX traceability editor and a browser that would be capable of storing not only SDoc documents but also any other artifacts that are reachable with SPDX. This work package is very ambitious and stretches the original scope of StrictDoc but is not impossible.

Let me know if anything of this resonates with you.

[stanislaw]

cc @nicpappler: FYI: this issue and my answer to @rosensymmetri

[rosensymmetri]

Thank you for the meaty response @stanislaw and happy new year!

• Do just want to have these external documents listed on the Index view and the TOC? How should the opening work? Just letting a whatever system app responsible for a format open the document?
• Do you also want to be able to refer to an external document from a requirement? Previously, one user suggested a special requirement link/relation type, let's call it External link. With this relation, it would be possible to refer to an URL of a given standard document, for example. To synthesize this earlier user feedback with your suggestion, I could imagine that two relation types would be needed: External document (your use case) and External link (just point to a URL, external to a project tree).

I imagine the way you suggest it, that the files are listed in the TOC and the Index view, and opening them defers to a system app. I think that file links would certainly be useful if the link was to a particular location in the document, it seems that file links to PDF can be to sections or pages. A colleague implemented a fork with PDF:s and HTML:s listed in the ToC and Index view, is that something that you would be interested in upstreaming?

• How should the document finding work? Do you want to hard-code a list of these external documents somewhere in the project config, or StrictDoc should auto-discover everything that has .doc, .rst, .html in an input folder, just like it does it for .sdoc?

Since you are asking for my opinion I think a useful config UX would be a config option for "External document path includes" (default: Empty) and "External document path excludes" (default: Empty). But this comes down to taste IMO and I don't want to hold a strong opinion about it. :)

• SPDX...

I had never heard about SPDX before, thanks for sharing, though it does not seem very central to my use cases.

[johanenglund]

As a first step, could we just have URLs found in String made into clickable links? This would allow me to at least add a custom "REFERENCE" field.

How come RST URLs (`Example <http:/ex.com/lnk>`_) works in STATEMENT and RATIONALE but not in custom String fields?

Ideally, I think, I'd would also want to be able to set a Parent RELATION to an URL in order to point to upstream hazard analysis and FMECAs. This field would not be possible to validate by strictdoc though so maybe this will break some philosophy?

[stanislaw]

When it comes to external links (leaving the external documents of this issue aside for now), something basic is very easy to implement once we agree on a concept. How about this?

[REQUIREMENT]
TITLE: Foo
STATEMENT: >>>
The system A shall do B.
<<<
RELATIONS:
- TYPE: ExternalURL
  VALUE: https://strictdoc.readthedocs.io/en/latest/

If a dedicated type is maintained for these external URLs, no philosophy will be affected.

How come RST URLs (Example [http:/ex.com/lnk](http://ex.com/lnk)_) works in STATEMENT and RATIONALE but not in custom String fields?

Please open an issue.