docs: Describe relations with and between specs #211

karfau · 2021-04-05T23:39:29Z

Fixes #119 and also gives some orientation while working on #203

brodybits · 2021-04-06T03:54:12Z

package.json

@@ -9,7 +9,8 @@
    "parser",
    "javascript",
    "DOMParser",
-    "XMLSerializer"
+    "XMLSerializer",
+    "ponyfill"


readme.md

brodybits · 2021-04-06T04:15:32Z

docs/puml.sh

+function svg {
+  if [[ -f "docs/$1.puml" ]] ; then
+    echo "updating docs/$1.svg"
+    < "docs/$1.puml" docker run --rm -i karfau/plantuml:$PLANTUML_VERSION -pipe -tsvg -nometadata > "docs/$1.svg"


For people like me who don't have so much extra horsepower to run Docker on my laptop, do you think it will work if I would use Ubuntu on the cloud? Would you recommend any resources if I need to install or configure anything?

The alternatives to using docker are

either have java installed and download the plantuml.jar and use the command < "docs/$1.puml" java -jar path/to/plantuml.jar -pipe ... instead. I added this as an option to the script, but depending on some OS dependencies (e.g. graphviz) versions the output can differ (this is what happened when I tried it locally).

or use the web interface http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000 (but I think it includes metadata which causes the generated to change every time)

Or we could of course also use some other format for creating images/diagrams for documentation purposes. This is just the one that supports many styles and I know how to use it.

brodybits · 2021-04-06T04:21:04Z

I would favor linking into MDN API documents in some (more?) places.

This looks really awesome in general. I may need 1-2 weeks or so to go through this more carefully, please ping me in case I slip on this one.

karfau · 2021-04-06T10:46:37Z

I would favor linking into MDN API documents in some (more?) places.

I think this is a good idea when linking to API docs, but the main purpose of this PR is to clarify the relations to those specs.

…specs

Since it's not that helpful at the beginning of the README. We will link to it when we either have a specific file about the topic of contribution docs.

karfau · 2021-04-17T20:31:30Z

Maybe it's good enough for now to not link to the achitecture diagram from the readme.

I changed that, for now the architecture (which is anyways more for internal use), is not linked anywhere.

I may need 1-2 weeks or so to go through this more carefully, please ping me in case I slip on this one.

Ping @brodybits

brodybits · 2021-04-18T01:54:36Z

I may need another week or so due to some other things that popped up, my apologies.

…specs

karfau · 2021-06-04T21:08:24Z

@brodybits Would love to get this landed, so that I can access those docs from master.
Any reason to still not land it?

brodybits · 2021-06-04T21:14:21Z

I will try to review this over the weekend (Sunday), please follow up in case I miss again.

brodybits

Overall I think this looks really good, left a few nits.

readme.md

brodybits · 2021-06-06T17:20:12Z

readme.md

+
+## Specs
+
+![Related specifications](docs/specs.svg)


nit: I don't know how accessible embedding this SVG would be to the visually impaired.

My understanding is that the visually impaired are able to read many websites with help from tools such as text-to-speech.

And another understanding is that at least in some parts of North America, free websites need to be accessible since they are considered public resources, and some less-abled people can sue website owners for websites that are not accessible enough.

I would assume that an SVG is more accessible than a PNG file, since it contains the text elements in a semantic manner.
I believe the related PUML file might even be less accessible because of it's weird syntax.
But I also have no clue if there would be a way to list this information in a textual manner including the relationships...

Of course I have no clue about the north american regulations.

Any recommendation?

I think that this is in any way a good starting point since it allows easier access to the related specs, even though not to everyone. Once we discussed which ones we consider relevant for our development we should be able to come up with a shortened textual representation with links to those relevant specs.

I think that this is in any way a good starting point

👍 agreed on my part

brodybits

And a minor nit, maybe not worth addressing, is that I would generally rather use Excalidraw for UML and other software diagrams. It is 100% open-source and I think it works via web or local Node.js.

karfau · 2021-06-06T19:20:03Z

And a minor nit, maybe not worth addressing, is that I would generally rather use Excalidraw for UML and other software diagrams. It is 100% open-source and I think it works via web or local Node.js.

Just wanted to add my perspective, which is why I created the diagrams this way: I personally prefer generating diagrams from some kind of source code, so they can be maintained and it's possible to ad comments to explain the thoughts behind it. Such a source code often also allows some semantic structuring which is harder to maintain with some visual tool or by hand writing SVGs.
Also I don't need to run any special software to be able to change the source, since it's just plain text. Of course there is usually some CLI to invoke (or website to copy paste the source to) to convert it to the diagram and IDE integration for live preview is preferable, to be able to see what my changes do with the diagram. That's why I pickt PUML, since it has a lot of options for different diagrams styles.

I'm fine if there would be some decision to another format at any point in time and willing to port this diagram over if suitable and possible. But for now I would not want to look for other options myself.

Co-authored-by: Chris Brody <git.brodybits@gmail.com>

and improve script name and comments in PUML files

brodybits

Thanks @karfau, all arguments sound reasonable to me.

karfau · 2021-06-06T19:39:28Z

@brodybits Do you think we can mark this PR as resolving #119 ?

Update: I just read through the issue again and I think this PR coveres everything.
Just reopen in case you think there is still something missing.

Co-authored-by: Chris Brody <git.brodybits@gmail.com>

docs: Document relation with and between specs

28da4df

karfau added the documentation Improvements or additions to documentation label Apr 5, 2021

karfau added this to the next release milestone Apr 5, 2021

karfau requested a review from brodybits April 5, 2021 23:39

karfau mentioned this pull request Apr 5, 2021

Document relationship between xmldom and standard Web APIs #119

Closed

brodybits reviewed Apr 6, 2021

View reviewed changes

package.json

@@ -9,7 +9,8 @@

"parser",

"javascript",

"DOMParser",

"XMLSerializer"

"XMLSerializer",

"ponyfill"

Copy link

Member

brodybits Apr 6, 2021

Choose a reason for hiding this comment

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

<3

brodybits reviewed Apr 6, 2021

View reviewed changes

readme.md Outdated Show resolved Hide resolved

brodybits mentioned this pull request Apr 6, 2021

Meta: Impact of "Superseeded" Status of DOM Level 2 Specification #176

Open

brodybits reviewed Apr 6, 2021

View reviewed changes

docs: Add java option to docs/puml.sh

ee42afe

karfau changed the title ~~docs: Document relation with and between specs~~ docs: Describe relations with and between specs Apr 6, 2021

karfau added 4 commits April 6, 2021 19:25

Merge remote-tracking branch 'upstream/master' into 119/203/document-…

832f2ea

…specs

docs: Add Infra Standard to the mix

90c1514

docs: Removed confusing link to architecture diagram.

d30495e

Since it's not that helpful at the beginning of the README. We will link to it when we either have a specific file about the topic of contribution docs.

Merge branch 'master' into 119/203/document-specs

95a25c9

Merge remote-tracking branch 'upstream/master' into 119/203/document-…

a591a8d

…specs

brodybits reviewed Jun 6, 2021

View reviewed changes

karfau and others added 2 commits June 6, 2021 21:22

docs(readme): Apply suggestions for improved wording

218f8be

Co-authored-by: Chris Brody <git.brodybits@gmail.com>

docs: Update plantuml version

efea6db

and improve script name and comments in PUML files

brodybits approved these changes Jun 6, 2021

View reviewed changes

karfau merged commit 87a708f into xmldom:master Jun 6, 2021

karfau deleted the 119/203/document-specs branch June 6, 2021 19:45

karfau added a commit to ChALkeR/xmldom that referenced this pull request Jul 27, 2021

docs: Describe relations with and between specs (xmldom#211)

7405590

Co-authored-by: Chris Brody <git.brodybits@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Describe relations with and between specs #211

docs: Describe relations with and between specs #211

karfau commented Apr 5, 2021 •

edited

brodybits Apr 6, 2021

brodybits Apr 6, 2021

karfau Apr 6, 2021 •

edited

brodybits commented Apr 6, 2021

karfau commented Apr 6, 2021

karfau commented Apr 17, 2021

brodybits commented Apr 18, 2021

karfau commented Jun 4, 2021

brodybits commented Jun 4, 2021

brodybits left a comment

brodybits Jun 6, 2021

karfau Jun 6, 2021

brodybits Jun 6, 2021

brodybits left a comment

karfau commented Jun 6, 2021

brodybits left a comment

karfau commented Jun 6, 2021 •

edited

docs: Describe relations with and between specs #211

docs: Describe relations with and between specs #211

Conversation

karfau commented Apr 5, 2021 • edited

brodybits Apr 6, 2021

Choose a reason for hiding this comment

brodybits Apr 6, 2021

Choose a reason for hiding this comment

karfau Apr 6, 2021 • edited

Choose a reason for hiding this comment

brodybits commented Apr 6, 2021

karfau commented Apr 6, 2021

karfau commented Apr 17, 2021

brodybits commented Apr 18, 2021

karfau commented Jun 4, 2021

brodybits commented Jun 4, 2021

brodybits left a comment

Choose a reason for hiding this comment

brodybits Jun 6, 2021

Choose a reason for hiding this comment

karfau Jun 6, 2021

Choose a reason for hiding this comment

brodybits Jun 6, 2021

Choose a reason for hiding this comment

brodybits left a comment

Choose a reason for hiding this comment

karfau commented Jun 6, 2021

brodybits left a comment

Choose a reason for hiding this comment

karfau commented Jun 6, 2021 • edited

karfau commented Apr 5, 2021 •

edited

karfau Apr 6, 2021 •

edited

karfau commented Jun 6, 2021 •

edited