xml: better README

xmppjs · Mar 14, 2021 · 42f9072 · 42f9072
1 parent dd6b4e3
commit 42f9072
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,5 @@
 # xmpp.js
 
-[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
-[![build status](https://img.shields.io/travis/xmppjs/xmpp.js/master.svg?maxAge=2592000&style=flat-square)](https://travis-ci.org/xmppjs/xmpp.js/branches)
-[![license](https://img.shields.io/github/license/xmppjs/xmpp.js.svg?maxAge=2592000&style=flat-square)](https://raw.githubusercontent.com/xmppjs/xmpp.js/master/LICENSE)
-
 > XMPP is an open technology for real-time communication, which powers a wide range of applications including instant messaging, presence, multi-party chat, voice and video calls, collaboration, lightweight middleware, content syndication, and generalized routing of XML data.
 
 > [xmpp.org/about-xmpp/technology-overview/](https://xmpp.org/about/technology-overview.html)

diff --git a/packages/xml/README.md b/packages/xml/README.md
@@ -2,7 +2,7 @@
 
 ## Install
 
-Note, if you're using `@xmpp/client` or `@xmpp/component`, you don't need to install `@xmpp/xml` yourself.
+Note, if you're using `@xmpp/client` or `@xmpp/component`, you don't need to install `@xmpp/xml`.
 
 `npm install @xmpp/xml` or `yarn add @xmpp/xml`
 
@@ -64,7 +64,7 @@ const message = (
 );
 ```
 
-Requires a [preprocessor](https://www.npmjs.com/package/babel-plugin-transform-react-jsx) such as [Babel](http://babeljs.io/) with [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx.html).
+Requires a preprocessor such as [TypeScript](https://www.typescriptlang.org/) or [Babel](http://babeljs.io/) with [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx.html).
 
 ## Reading
 
@@ -201,19 +201,9 @@ const body = message.getChild("body");
 message.remove(body);
 ```
 
-## Parsing XML string
-
-To parse a string into an XML Element, there's a helper script included in the module.
-
-```js
-const parse = require('@xmpp/xml/lib/parse');
-const ctx = parse('<message><body>hello world</body></message>');
-ctx.getChildText("body"); // hello world
-```
-
 ## JSON
 
-You can embed JSON anywhere but it is recommended to use an appropriate semantic.
+You can embed JSON anywhere but it is recommended to use appropriate semantic.
 
 ```js
 /** @jsx xml */
@@ -234,3 +224,30 @@ JSON.parse(
 ```
 
 See [JSON Containers](https://xmpp.org/extensions/xep-0335.html)
+
+## Parsing XML strings
+
+`@xmpp/xml` include a function to parse XML strings.
+
+⚠ Use with care. Untrusted input or substitutions can result in invalid XML and side effects.
+
+```js
+const { escapeXML, escapeXMLText };
+const parse = require("@xmpp/xml/lib/parse");
+
+const ctx = parse("<message><body>hello world</body></message>");
+ctx.getChildText("body"); // hello world
+```
+
+If you must use with untrusted input, escape it with `escapeXML` and `escapeXMLText`.
+
+```js
+const { escapeXML, escapeXMLText } = require("@xmpp/xml");
+const parse = require("@xmpp/xml/lib/parse");
+
+const message = parse(`
+  <message to="${escapeXML(to)}">
+    <body>${escapeXMLText(body)}</body>
+  </message>,
+`);
+```