Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Handle third party trademarks #168

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Handle third party trademarks #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7776200
Annotate third party trademarks in documentation with '*'
lwaern-intel Mar 21, 2023
e213c9e
Enforce annotation for third party trademarks in the reference manual
lwaern-intel Mar 21, 2023
e19ff23
DML wiki: add acknowledgement line for any page with a third party tr…
lwaern-intel Mar 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion RELEASENOTES-1.4.docu
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -445,7 +445,7 @@
for huge (multi-megabyte) struct types
<bug number="18026246959"/>.</add-note></build-id>
<build-id value="6205"><add-note> <tt>--coverity</tt> has been added as an
option to DMLC. When used, DMLC will generate Synopsys® Coverity® analysis
option to DMLC. When used, DMLC will generate Synopsys* Coverity* analysis
annotations to suppress common false positives in generated C code created
from DML 1.4 devices.</add-note></build-id>
<build-id value="6205"><add-note> Fixed an ICE caused by constant inlined
Expand Down
2 changes: 1 addition & 1 deletion RELEASENOTES.docu
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1536,7 +1536,7 @@
<build-id value="6036"><add-note> Adjusted DMLC code generation to silence
false positives
reported on <file>dml-builtins.dml</file> when analysing
DMLC-generated C code using the Synopsis&reg; Coverity&reg;
DMLC-generated C code using the Synopsys* Coverity*
static analysis tool. </add-note></build-id>
<build-id value="6044"><add-note> Improved some error messages <bug
number="SIMICS-15552"/>.</add-note></build-id>
Expand Down
2 changes: 1 addition & 1 deletion doc/1.4/running-dmlc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ causes generated C code to follow the DML code more closely.
--coverity
</dt><dd>

Adds Synopsys® Coverity® analysis annotations to suppress common false positives
Adds Synopsys* Coverity* analysis annotations to suppress common false positives
in generated C code created from DML 1.4 device models.
</dd><dt>

Expand Down
8 changes: 8 additions & 0 deletions md_to_github.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@ def toc_md_files(toc, indices):
-->
'''

acknowledgement = r'''
***
<sub>\* Other names and brands may be claimed as the property of others.</sub>
'''

Comment on lines +56 to +60
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be part of the md_to_github script: The md sources are compiled into both simics-native docs and into github wiki, so better fix this in the md sources instead. Or is this stuff also auto-added by dodoc?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Simics Online Documentation will have a separate solution that won't require authors to manually add acknowledgment lines. So this DML wiki exclusive logic should indeed be DML wiki exclusive.

Copy link
Contributor Author

@lwaern-intel lwaern-intel Mar 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively... the DML wiki could have a * Legal Information page... hmm...

Though that could be more cumbersome than an acknowledgement line (or awkward, if all it contains is the acknowledgement line)

frontpage_links = []

filename_map = {}
Expand Down Expand Up @@ -93,6 +98,9 @@ def add_to_tar(tf, path, contents):
end = match.end(1)
if end > start:
body = body[:start] + filename_map[match[1]] + body[end:]

if validate_md_links.third_party_trademark_re.search(body) is not None:
body += acknowledgement
add_to_tar(tgz, path, copyright + body)

head = [copyright,
Expand Down
4 changes: 2 additions & 2 deletions py/dml/dmlc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -374,12 +374,12 @@ def set_debuggable(option, opt, value, parser):
+ ' --strict-dml12.')

# <dt>--coverity</dt>
# <dd> Adds Synopsys® Coverity® analysis annotations to suppress common
# <dd> Adds Synopsys* Coverity* analysis annotations to suppress common
# false positives in generated C code created from DML 1.4 device models.
# </dd>
optpar.add_option(
'--coverity', dest = 'coverity', action = 'store_true',
help = ('Adds Synopsys® Coverity® analysis annotations to suppress '
help = ('Adds Synopsys* Coverity* analysis annotations to suppress '
+ 'common false positives in generated C code created from '
+ 'DML 1.4 device models.'))
# <dt>--noline</dt>
Expand Down
35 changes: 35 additions & 0 deletions validate_md_links.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ def toc_md_files(toc, dirs):

assert anchor_re.findall('<a id="comparison-to-c"/>') == ['comparison-to-c']

third_party_trademarks = {'synopsys', 'coverity'}

third_party_trademark_re = re.compile(
r'(?i:(' + '|'.join(third_party_trademarks)
+ r'))([*®™]|&reg;|&trade;|&copy;|\\\*)?')
Comment on lines +29 to +31
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

urgh, I can't read this. Can you document what you mean with a unit test? A simple assert third_party_trademark_re.match(...) == ... on top level is sufficient.

Also, if you want to capture this in the future, then I suggest allowlist rather than blocklist, i.e. complain if the word before ® or ™ does not match smth like Intel, Simics, DML.

Copy link
Contributor Author

@lwaern-intel lwaern-intel Mar 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

urgh, I can't read this. Can you document what you mean with a unit test? A simple assert third_party_trademark_re.match(...) == ... on top level is sufficient.

The regex can actually be improved a small bit (the second group doesn't need to try to match against anything but * or \*), but yes, I can do a unit test.

Also, if you want to capture this in the future, then I suggest allowlist rather than blocklist, i.e. complain if the word before ® or ™ does not match smth like Intel, Simics, DML.

Not good enough, that doesn't catch people using an external trademark without annotating it with an *, and that's the main point of the check.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I want to keep the regex as-is and capitalize on it instead. Currently we check that an external trademark is annotated with * at least once per section it's referenced in. However, we should also check that no reference to an external trademark is annotated with ® or ™.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you want to protect from using external trademarks without *, then you need a much bigger list, because the world has more than two trademarked things.

And if we are to make this kind of check, then it's better to do it globally for all simics docs.


def char_range(low, high):
return map(chr, range(ord(low), ord(high) + 1))

Expand Down Expand Up @@ -95,11 +101,40 @@ def main():
line = md_files[path][:match.start()].count('\n') + 1
sys.stderr.write(f'{path}:{line}: error: {message}\n')
ok = False

third_party_trademarks_referenced = {}
third_party_trademarks_annotated = set()
def check_third_party_trademarks():
for (tm, line) in third_party_trademarks_referenced.items():
if tm not in third_party_trademarks_annotated:
sys.stderr.write(
f"{path}:{line+1}: error: third party trademark "
+ f"'{tm}' never annotated with '*' in this section\n")
nonlocal ok
ok = False
third_party_trademarks_referenced.clear()
third_party_trademarks_annotated.clear()

for (i, line) in enumerate(md_files[path].split('\n')):
if ' -- ' in f' {line} ':
sys.stderr.write(
f'{path}:{i+1}: error: replace -- with &mdash;\n')
ok = False

# A third party trademark must be annotated at least once per
# (sub)section
if line.startswith('#'):
check_third_party_trademarks()
for match in third_party_trademark_re.finditer(line):
annotated = match.group(2) in {'*', '\\*'}

tm = match.group(1).lower()
third_party_trademarks_referenced.setdefault(tm, i)
if annotated:
third_party_trademarks_annotated.add(tm)

check_third_party_trademarks()

sys.exit(0 if ok else 1)

if __name__ == '__main__':
Expand Down