Commit a3ca6a5

committed

Refactor docs

1 parent 34c6cbb commit a3ca6a5Copy full SHA for a3ca6a5

File tree

1 file changed

+53

-32

lines changed

readme.md

1 file changed

+53

-32

lines changed

`‎readme.md‎`

Lines changed: 53 additions & 32 deletions

Original file line number	Diff line number	Diff line change
`@@ -50,30 +50,36 @@ Development started in January 2020.`
`50`	`50`
`51`	`51`	`### Where this specification fits`
`52`	`52`
`53`		`-xast extends [unist][], a format for syntax trees, to benefit from its`
`54`		`-[ecosystem of utilities][utilities].`
	`53`	`+xast extends [unist][],`
	`54`	`+a format for syntax trees,`
	`55`	`+to benefit from its [ecosystem of utilities][utilities].`
`55`	`56`
`56`	`57`	`xast relates to [JavaScript][] in that it has an [ecosystem of`
`57`	`58`	`utilities][list-of-utilities] for working with compliant syntax trees in`
`58`	`59`	`JavaScript.`
`59`		`-However, xast is not limited to JavaScript and can be used in other programming`
	`60`	`+However,`
	`61`	`+xast is not limited to JavaScript and can be used in other programming`
`60`	`62`	`languages.`
`61`	`63`
`62`	`64`	`xast relates to the [unified][] project in that xast syntax trees are used`
`63`	`65`	`throughout its ecosystem.`
`64`	`66`
`65`	`67`	`### Scope`
`66`	`68`
`67`		`-xast represents XML syntax, not semantics: there are no namespaces or local`
`68`		`-names; only qualified names.`
	`69`	`+xast represents XML syntax,`
	`70`	`+not semantics:`
	`71`	`+there are no namespaces or local names;`
	`72`	`+only qualified names.`
`69`	`73`
`70`	`74`	`xast supports a sensible subset of XML by omitting the ostensibly bad DTD.`
`71`		`-XML processors are not guaranteed to process DTDs, making them unsafe.`
	`75`	`+XML processors are not guaranteed to process DTDs,`
	`76`	`+making them unsafe.`
`72`	`77`
`73`	`78`	`xast represents expanded entities and therefore does not deal with entities or`
`74`	`79`	`character references.`
`75`		`-It is suggested that utilities around xast, that parse or serialize, do not`
`76`		`-support [parameter-entity references][concept-parameter-entity] or`
	`80`	`+It is suggested that utilities around xast,`
	`81`	`+that parse or serialize,`
	`82`	`+do not support [parameter-entity references][concept-parameter-entity] or`
`77`	`83`	`[entity references][concept-entity] other than the`
`78`	`84`	`[predefined entities][concept-predefined-entities]`
`79`	`85`	(`<` for `<` U+003C LESS THAN;
`@@ -110,8 +116,8 @@ Internal document type declarations have no representation in xast:`
`110`	`116`
`111`	`117`	`## Types`
`112`	`118`
`113`		`-If you are using TypeScript, you can use the xast types by installing them`
`114`		`-with npm:`
	`119`	`+If you are using TypeScript,`
	`120`	`+you can use the xast types by installing them with npm:`
`115`	`121`
`116`	`122`	```sh
`117`	`123`	`npm install @types/xast`
`@@ -156,7 +162,8 @@ interface Cdata <: Literal {`
`156`	`162`	`Cdata ([Literal][dfn-literal]) represents a`
`157`	`163`	`[CDATA section][concept-cdata] ([\[XML\]][xml]).`
`158`	`164`
`159`		`-For example, the following XML:`
	`165`	`+For example,`
	`166`	`+the following XML:`
`160`	`167`
`161`	`168`	```xml
`162`	`169`	`<![CDATA[<greeting>Hello, world!</greeting>]]>`
`@@ -182,7 +189,8 @@ interface Comment <: Literal {`
`182`	`189`	`Comment ([Literal][dfn-literal]) represents a`
`183`	`190`	`[comment][concept-comment] ([\[XML\]][xml]).`
`184`	`191`
`185`		`-For example, the following XML:`
	`192`	`+For example,`
	`193`	`+the following XML:`
`186`	`194`
`187`	`195`	```xml
`188`	`196`	`<!--Charlie-->`
`@@ -211,14 +219,17 @@ interface Doctype <: Node {`
`211`	`219`	A `name` field must be present.
`212`	`220`
`213`	`221`	A `public` field should be present.
`214`		`-If present, it must be set to a string, and represents the document’s public`
`215`		`-identifier.`
	`222`	`+If present,`
	`223`	`+it must be set to a string,`
	`224`	`+and represents the document’s public identifier.`
`216`	`225`
`217`	`226`	A `system` field should be present.
`218`		`-If present, it must be set to a string, and represents the document’s system`
`219`		`-identifier.`
	`227`	`+If present,`
	`228`	`+it must be set to a string,`
	`229`	`+and represents the document’s system identifier.`
`220`	`230`
`221`		`-For example, the following XML:`
	`231`	`+For example,`
	`232`	`+the following XML:`
`222`	`233`
`223`	`234`	```xml
`224`	`235`	`<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">`
`@@ -261,10 +272,11 @@ It represents information associated with the element.`
`261`	`272`	The value of the `attributes` field implements the
`262`	`273`	`[Attributes][dfn-attributes] interface.`
`263`	`274`
`264`		`-For example, the following XML:`
	`275`	`+For example,`
	`276`	`+the following XML:`
`265`	`277`
`266`	`278`	```xml
`267`		`-<package xmlns="http://www.idpf.org/2007/opf"unique-identifier="id" />`
	`279`	`+<package unique-identifier="id"xmlns="http://www.idpf.org/2007/opf" />`
`268`	`280`	```
`269`	`281`
`270`	`282`	`Yields:`
`@@ -274,8 +286,8 @@ Yields:`
`274`	`286`	`type: 'element',`
`275`	`287`	`name: 'package',`
`276`	`288`	`attributes: {`
`277`		`- xmlns: 'http://www.idpf.org/2007/opf',`
`278`		`- 'unique-identifier': 'id'`
	`289`	`+ 'unique-identifier': 'id',`
	`290`	`+ xmlns: 'http://www.idpf.org/2007/opf'`
`279`	`291`	`},`
`280`	`292`	`children: []`
`281`	`293`	`}`
`@@ -295,7 +307,8 @@ interface Instruction <: Literal {`
`295`	`307`
`296`	`308`	A `name` field must be present.
`297`	`309`
`298`		`-For example, the following XML:`
	`310`	`+For example,`
	`311`	`+the following XML:`
`299`	`312`
`300`	`313`	```xml
`301`	`314`	`<?xml version="1.0" encoding="UTF-8"?>`
`@@ -326,8 +339,9 @@ document.`
`326`	`339`	`must not be used as a [child][term-child].`
`327`	`340`
`328`	`341`	`XML specifies that documents should have exactly one [element][dfn-element]`
`329`		`-child, therefore a root should have exactly one element child when representing`
`330`		`-a whole document.`
	`342`	`+child,`
	`343`	`+therefore a root should have exactly one element child when representing a`
	`344`	`+whole document.`
`331`	`345`
`332`	`346`	### `Text`
`333`	`347`
`@@ -340,7 +354,8 @@ interface Text <: Literal {`
`340`	`354`	`Text ([Literal][dfn-literal]) represents`
`341`	`355`	`[character data][concept-char] ([\[XML\]][xml]).`
`342`	`356`
`343`		`-For example, the following XML:`
	`357`	`+For example,`
	`358`	`+the following XML:`
`344`	`359`
`345`	`360`	```xml
`346`	`361`	`<dc:language>en</dc:language>`
`@@ -388,9 +403,10 @@ typedef string AttributeValue`
`388`	`403`	`Attribute values are values on [Attributes][dfn-attributes] objects and must`
`389`	`404`	`reflect XML attribute values exactly as a string.`
`390`	`405`
`391`		-> In [JSON][], the value `null` must be treated as if the attribute was not
`392`		`-> included.`
`393`		-> In [JavaScript][], both `null` and `undefined` must be similarly ignored.
	`406`	`+> In [JSON][],`
	`407`	+> the value `null` must be treated as if the attribute was not included.
	`408`	`+> In [JavaScript][],`
	`409`	+> both `null` and `undefined` must be similarly ignored.
`394`	`410`
`395`	`411`	`## Glossary`
`396`	`412`
`@@ -456,12 +472,17 @@ ways to get started.`
`456`	`472`	See [`support.md`][support] for ways to get help.
`457`	`473`	Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas].
`458`	`474`
`459`		`-A curated list of awesome syntax-tree, unist, hast, mdast, nlcst, and xast`
`460`		`-resources can be found in [awesome syntax-tree][awesome].`
	`475`	+A curated list of awesome `syntax-tree`,
	`476`	`+unist,`
	`477`	`+hast,`
	`478`	`+mdast,`
	`479`	`+nlcst,`
	`480`	`+and xast resources can be found in [awesome syntax-tree][awesome].`
`461`	`481`
`462`	`482`	`This project has a [code of conduct][coc].`
`463`		`-By interacting with this repository, organization, or community you agree to`
`464`		`-abide by its terms.`
	`483`	`+By interacting with this repository,`
	`484`	`+organization,`
	`485`	`+or community you agree to abide by its terms.`
`465`	`486`
`466`	`487`	`## Acknowledgments`
`467`	`488`

0 commit comments

Comments

(0)

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Commit a3ca6a5

File tree

1 file changed

1 file changed

`‎readme.md‎`

0 commit comments