[update] grammar and style in Grid guides - #153
Open
serhiipylypchuk1991 wants to merge 7 commits into
Open
serhiipylypchuk1991 wants to merge 7 commits into
serhiipylypchuk1991 wants to merge 7 commits into
Conversation
- the intro was passive twice: "DHTMLX Grid is built to be operated entirely from the keyboard and to expose its structure"; now "You can operate DHTMLX Grid entirely from the keyboard, and the Grid exposes its structure" - "e.g." twice in Host-page responsibilities -> "for example" and "such as", per the abbreviations rule - "Make sure the host document:" was an intro the list items had to finish grammatically (sets, provides, gives). Now "In the host page:" with imperative items and periods instead of semicolons - "are on by default — there is no flag to turn them off" stated for the third time what line 9 and the sample comment already say; the fact now lives in one place, which also removes the "by default" phrasing - "is on by default (keyNavigation: true)" -> "is enabled by the default keyNavigation: true" - "the row's depth" -> "the row depth", per the possessives rule - the value in **"range"** mode was bold; values take backticks - dropped the trailing period on the last "Covered areas" item, the other four have none Left as is: **no**, **footer** and **zones** stay bold. They are ordinary words rather than API names, which the skill allows. Headings are untouched; the page links to #host-page-responsibilities itself.
Factual errors: - the note under "patternMask" documented an `inputMask` property that does not exist in Grid: it was the only occurrence in all of docs/grid/, the section describes `patternMask`, and `charFormat` is a property of `patternMask`. The same non-existent property was already corrected in form/work_with_form.md - the numberMask section linked `getValue()` to form/api/form_getvalue_method.md from a Grid page. Grid has no getValue method at all; form/work_with_form.md:170 carries the same sentence with `inputType:"text"` and the correct Input link, so the text was copied over from the Form docs. Reworded to describe the value stored in the data item instead of citing a missing API Broken code samples: - the header/footer height sample had `footerRowHeight:50` with no comma before `headerRowHeight`, making the object literal invalid - the header/footer tooltipTemplate sample never closed the `new dhx.Grid(...)` call: `});` was missing before the closing fence Grammar and style, ~160 replacements: - i.e., e.g. and etc. removed; `***bold italic***` on property names replaced with backticks - "There is a possibility to", "you should", "you need to" and "In the above example" rewritten - "DHTMLX Grid possesses flexible configuration that let you get desired look and feel" - subject-verb disagreement in the opening line - customFilter was called an attribute in three places; it is a property - ComboBox and Combo Box normalized to Combobox - typos: "with your you own logic", "its row/colmn", "events handlers" - the DragPanel option list was indented four spaces with no parent list item, so it rendered as a nested list; dedented No heading was touched, so all 73 inbound anchors to this page stay valid. Frontmatter untouched. Trailing whitespace is net zero: 23 lines removed, 23 added, 24 characters each way. Docusaurus build passes. Left alone as site-wide conventions: "Roman alphabet" (also in the already-rewritten form/work_with_form.md), "obligatory" (15 uses), and backticks inside raw <td> (71 uses).
Critical:
- the "Styling cells" sample called
grid.addCellCss(rowId, "country", "my_сustom_сlass") with two
Cyrillic с (U+0441) inside a Latin identifier, and that class is
defined nowhere: the <style> block of the same sample declares
.myCustomClass. The sample could not work as written. The sibling
sample above it pairs .myCustomClass with "myCustomClass" correctly,
so the intended value is unambiguous. Only the legitimate ² in "Km²"
remains non-ASCII in the file
Rendering:
- the closing note used the old {{note ...}} macro, which Docusaurus
printed literally, braces and all; converted to :::note. Roughly 20
other files still carry {{note}} and are left untouched
- <br> aligned with <br/> as used in the two other tables
API name formatting, 9 occurrences:
- **text**, **rowCss**, **addRowCss()**, **addCellCss()**, **mark**,
**template** and **tooltipTemplate** moved from bold to backticks,
plus the plain-text [css] and [tooltipTemplate] link labels
Grammar and style:
- "via" replaced three times, and "via using the ... property" once
- "an object which takes two optional parameters" - restrictive clause,
so "that"
- weak openers rewritten: "There is a possibility to make changes in",
"It is possible to change", "It is easy to style", "It is also
possible to highlight"
- "You can easily set some styling ... by applying some inline style"
carried a filler adverb, two indefinite pronouns and a by-ing link
- of-chains: "the header of a column" -> "the column header",
"the content of cells of Grid" -> "the content of Grid cells",
"the tooltip of a column" -> "a column tooltip"
- "add a new CSS class(es)" - article against a plural marker
- "As a value of property" -> "As the value of the property"
- missing comma after the introductory "For this"
- a list item that introduces a code sample ended with a period while
its sibling ended with a colon
No heading was touched, so all 8 inbound anchors to this page stay
valid. Frontmatter untouched. Trailing whitespace is net zero.
Rendering:
- the PRO notice used the old {{pronote ...}} macro, which Docusaurus
printed literally, braces and all. Converted to :::tip Pro version
only - the capitalized form leads 15 to 6 in docs/grid/, and
usage_blockselection.md, usage_history.md and usage_rangeselection.md
carry the identical body sentence, so the text is unchanged. Seven
other files still carry {{pronote}} and are left untouched
API name formatting:
- **load()** and **serialize()** moved from bold to backticks, plus the
plain-text [data] link label
Tenses - future or passive where present simple belongs, 5 places:
- "The component will make an AJAX call and expect" -> makes / expects
- "In this case they will be generated automatically" -> "in this case,
Grid generates them automatically"
- "In case you haven't specified ids of rows, they will be
auto-generated" -> "If you don't specify row ids, Grid generates them
automatically"
- "Thus the data from the first data line will be used as keys of items"
-> "The first data line then provides the item keys"
- "will not work until all data are loaded" -> "does not work until all
data is loaded"
Punctuation:
- two list introductions were completed by their own items ("you need
to:"); both now read "do the following:"
Grammar and style:
- "in the JSON format" -> "in JSON format"; a standalone format name
takes no article
- "contains configuration of a grid row" -> "the configuration"
- "where key is the id of a column and value is" -> "where the key is
... and the value is"
- of-chains: "ids of rows", "the file with data", "keys of items",
"the data of a grid"
- "make use of" -> "use"; "via the load() method" -> "with"
- "Please note that" dropped - the sentence already sits in an :::info
block; "should be" -> "must be", since it is a requirement
- "they are reapplied to the newly loaded data" -> "Grid reapplies
them"; the passive hid the actor
- "The structure of a row is rather flexible." removed as an empty
generalization, and the sentence merged with its neighbour
- weak openers reworked: "There are several ways of loading data",
"Here is an example", "Then you can parse"
Left alone: **unique** on line 25 is bold on an ordinary prose word,
not an API name, which the rules allow explicitly.
No heading was touched, so the three inbound anchors and the four
in-page ones stay valid. Frontmatter untouched. Trailing whitespace is
net zero.
Rendering:
- the case-insensitivity note used the old {{note ...}} macro, which
Docusaurus printed literally, braces and all; converted to :::note.
93 files still carry {{note}} and are left untouched
API name formatting, 3 occurrences:
- **grid.events.on()**, **grid.events.detach()** and
**grid.events.fire()** moved from bold to backticks
Grammar and style:
- "The names of events are case-insensitive" -> "Event names are
case-insensitive"
- "The full list of events is available in the related [API section]"
-> "For the full list of events, see the related [API section]"
- the first section opened with "You can attach event listeners with
the ... method:" while the other two used "To <verb> events, use ...".
All three now read "To <verb> ..., use the `...` method:", which also
matches the closest sibling page, chart/events.md
Left alone: the gerund section headings ("Attaching event listeners",
"Calling events") violate the gerunds-in-titles rule, but a heading is
an anchor and the review rules forbid changing one in a fix. This page
happens to have no inbound anchors, so it would have been safe, but no
heading has been touched anywhere in this pass.
Frontmatter untouched. Trailing whitespace is net zero.
Grammar errors: - "Learn how to to automatically add an empty row" carried a doubled "to" - "make the size of columns to automatically adjust to their content" used the ungrammatical "make X to do" pattern Abbreviations: - "for working with data of Grid, i.e. edit, add, remove, sort data, etc." packed i.e. and etc. into one sentence; rewritten as "to work with Grid data: edit, add, remove, and sort it" Consistency - the dominant defect on this page: - 26 section introductions used seven different phrasings for the same job: "you will get to know how to" x12, "you will find the ways of" x5, "you can learn how to" x3, "you will learn" x4, "you can find out" x2, plus "This section will tell you" and "This section explains". All now read "In this section you will learn...". "you will get to know how to" appears in exactly one file site-wide (this one), while "In this section you will learn" appears in 20, so this returns the page to the house pattern rather than inventing one - "Read how" (2) aligned with "Learn how" (120) - "use API of the X module" -> "use the API of the X module" in three rows, and the Selection row now matches the API reference table - "the interface of dhtmlxGrid" -> "of Grid"; the legacy spelling still sits in three other Grid files - "the TreeGrid mode of the Grid widget" -> "the TreeGrid mode of the Grid component", also dropping a stray double space Articles, 9 places: - "from external file", "from external DataCollection", "use DHTMLX Optimus framework ... creating DHTMLX-based app", "define initial structure", "set specific size", "into data of Grid cells", "an object with configuration of", "to exact position", "corresponding references" Word choice: - restrictive "which" -> "that" in three rows; "maximal width" -> "maximum width", matching "minimum" in the next row - "perform the code" -> "run the code", and the possessive "the component's rendering" -> "the component renders" - the page intro said "go into deep dive on its functionality", a broken idiom; now "dive deep into its functionality". The same sentence sits in all 20 features.md pages and is left untouched there Left alone: **Grid API** and **DataCollection API** stay bold. They are prose names of API surfaces, not code identifiers, and the rules allow bold on ordinary prose words. No heading was touched and this page has no inbound anchors. Frontmatter untouched. Trailing whitespace is net zero. Every table row still has the same three-cell shape.
Opening paragraph: - "JavaScript component which allows creating tables" - restrictive clause, so "that", and "allows creating" becomes "allows you to create", the form the gerund rule prescribes - "DHTMLX Grid provides great possibilities for customizing its look and feel." -> "You can customize its look and feel." The verb is on the overused list and "great possibilities" is marketing; the rewrite also drops the second "DHTMLX Grid" in two consecutive sentences - "Complete JavaScript API is provided to help users save time on configuring." -> "A complete JavaScript API helps you save time on configuration." The passive hid the actor and the article was missing Guides intro: - "Says how to build a standard grid on a page ... attach events, etc." had no subject at all, left "configure with specific settings" without an object, and closed a colon list with etc. Now reads "These guides explain how to build ... configure it with specific settings, customize the appearance, and attach events." This wording appears in no other index.md, so it was a local defect rather than a template Related resources: - three introductory phrases were missing their comma (lines 28, 30, 31) - "data of Grid" -> "Grid data" in two rows Left alone, with reasons: - dhtmlxGrid on line 27 sits inside a link target (products/dhtmlxGrid/download.shtml). Link targets are out of scope and a fix may never change one, so the legacy spelling stays - the empty [](...) link labels are the site convention - trailing whitespace on lines 3, 11 and 42 is preserved byte-for-byte - "There are also [online samples...]" is shared by 21 index pages Still carrying the same defects elsewhere: "To work with data of X check [...]" in 9 other index pages, and the comma-less "To get the whole JavaScript library of UI components" in 2 more. No heading was touched and this page has no inbound anchors. Frontmatter untouched. No link target changed. Trailing whitespace is net zero.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Left as is: no, footer and zones stay bold. They are ordinary words rather than API names, which the skill allows. Headings are untouched; the page links to #host-page-responsibilities itself.