[update] grammar and style in Layout guides - #155
Open
serhiipylypchuk1991 wants to merge 9 commits into
Open
serhiipylypchuk1991 wants to merge 9 commits into
serhiipylypchuk1991 wants to merge 9 commits into
Conversation
First file outside docs/grid/ in this pass.
Typos and agreement:
- "attribute into the the object of a cell(s)" - doubled "the"
- "if there is no any component or HTML content attached" - "no any"
- "there is no space and borders between cells" - singular verb with a
plural subject, and a missing comma before the following clause
Wrong verb:
- "the second one checks whether a cell is collapsed during the
initialization of a layout". The `collapsed` property sets the
initial state, it does not test it. Now "the second defines whether a
cell is collapsed when a layout is initialized", which also drops the
weak "There are two attributes of..." opener
Rendering:
- the two {{note ...}} macros on lines 140 and 231 printed literally,
braces and all; converted to :::note. Line 140 also lost a redundant
"Note, that" inside the note itself and a stray trailing space.
127 occurrences across 94 files remain elsewhere
Grammar and style:
- "make use of" -> "use"; "with the help of corresponding attributes"
was also missing its article
- "You can easily control and change the size of a cell via the" - a
filler adverb, a redundant pair, and via
- "As you can see from the code example above" -> "In the example
above"; the rules list that opener explicitly
- "width/ height" carried stray spaces after the slashes, and "would
automatically adjust" was hypothetical where the present tense belongs
- future tense on lines 87 and 213, and "Note," -> "Note that"
Reported, not fixed - a genuinely broken anchor:
- layout_cell_headerimage_config.md:22 and
layout_cell_headericon_config.md:24 link to
cell_configuration.md#cellheader, but the heading "Cell header"
slugifies to #cell-header, which is what layout/features.md:49 uses.
This file is the only cell_configuration.md in the tree, so it is not
a name collision. Both links sit in other files, inside [comment]:
lines the review excludes, and a fix may not change a link target
Left alone, each measured rather than assumed:
- "maximal and minimal sizes" on line 124 stays. Site-wide those forms
lead 49/46 against 14/14 for maximum/minimum, and the line uses both
consistently. The same change was made in grid/features.md only
because the adjacent row already said "minimum"
- "By default" on lines 216 and 238 stays: 40 sentence openers and 793
mid-sentence uses across the tree
No heading was touched, so all 11 inbound anchors stay valid.
Frontmatter untouched. No link target changed. None of the 18 changed
lines falls inside a code fence. Trailing whitespace is net zero.
Samples that do not work as written: - line 37 used `row: [` where the Layout config property is `rows`. The API reference has layout_rows_config.md and layout_cols_config.md but no page for a singular `row`, and no file documents a 'row?:' signature. Across all of docs/layout/ the singular form appeared in exactly this one line, while line 82 of the same file already used `rows:`. Copying the sample would produce a layout with no rows - line 27 defined `.my_second-class` with a hyphen while the config sets css:"my_first_class my_second_class" with an underscore, so that class never applied. Of the 18 files carrying the identical config line, 12 define the underscore form and only 3 the hyphen, so the style block was the outlier. pagination/customization.md and tree/setting_tree_appearance.md still have the same mismatch Grammar and style in the shared opener: - "There is a possibility to make changes in the look and feel" -> "You can change the look and feel" - "For this you need to take the following steps:" - missing comma after the introductory phrase, and "you need to" padding an imperative - "add a new CSS class(es) with desired settings" put an article in front of a plural marker -> "add one or more CSS classes with the desired settings"; the parenthetical was reordered to read straight - [css] -> [`css`], a config property in a plain-text link label That opener is shared by 20 */customization.md files. They are untouched here, and none of them carries the corrected wording yet: the grid version was rewritten on sp-next-grid-article-grammar, which this branch does not contain. The work list is empty after the rewrite, with no dismissals required. No heading was touched and this page has no inbound anchors. Frontmatter untouched. No link target changed. Only lines 27 and 37 fall inside a code fence, which are the two intentional sample fixes. Trailing whitespace is net zero.
API name formatting, 3 occurrences:
- **layout.events.on()**, **layout.events.detach()** and
**layout.events.fire()** moved from bold to backticks
Rendering:
- the case-insensitivity note used the {{note ...}} macro, which
Docusaurus prints literally. Converted to :::note. This page has the
multi-line variant, which is the rare one: 9 across the tree against
112 single-line, so the replacement had to match the marker
byte-exact, including its trailing space
Address and voice:
- line 11 said "The user can add ... To do this, the user can use",
third person twice where the rest of the page addresses "you", and
repeated "any ... to any of"
- "Several handlers can be attached to one and the same event, and all
of them will be executed" carried two passives, the redundant pair
"one and the same", and the future tense. Now "You can attach several
handlers to the same event, and Layout executes all of them"
- "There is a simple way of removing an event handler via the ...
method" -> "To remove an event handler, use the ... method"
- "The names of the events are case-insensitive" -> "Event names are
case-insensitive"
On consistency: none of this could be justified by pointing at
grid/events.md. The corrected wording exists in exactly one file
tree-wide, and that file is on sp-next-grid-article-grammar, which this
branch does not contain. Each change stands on its own rule.
Trailing whitespace is -1 character. The only removed line ending in
whitespace is '{{note ', and no added line carries any: that space
belonged to the macro marker being replaced, not to surrounding prose.
The sole remaining trailing space in the file is line 3, frontmatter.
The same patterns remain elsewhere and are untouched: "The user can add
any user-defined handler" in 3 files, "There is a simple way of removing
an event handler" in 8, "The names of the events are case-insensitive"
in 9, bold **x.events.on()** in 19 files, and {{note}} in 93.
The work list is empty after the rewrite, with no dismissals required.
No heading was touched and this page has no inbound anchors. Frontmatter
untouched. No link target changed. No changed line falls inside a code
fence.
Broken wording carried by the features.md template: - "go into deep dive on its functionality" -> "dive deep into its functionality". Still present in 19 other features.md pages - "Learn how to perform the code after the component's rendering" -> "run the code after the component renders". "perform the code" was the only form in the tree, with no occurrence of "run the code"; 19 files still carry it A row that contradicted itself: - line 63 labelled the link "Height of the cell's header" while its description now reads "the height of a cell header". That possessive was the only one in the file and a lone outlier site-wide, 1 hit in 1 file against "cell header" 3 in 2. The label is prose and was changed; the link target was not. 0 files still use the possessive Grammar and style: - line 13 wrote "initialize Layout" and then "integrate a Layout" in one sentence - the Optimus row was missing two articles and carried a double space - "in the absence of the component/HTML content in the cell" was padded and repeated "in a cell ... in the cell" - "attach HTML content into a cell" takes "to", not "into" - "etc." closed an enumeration on line 79 - one row offered "Example 1" beside an unnumbered "Example" - line 142 was missing an article, and "Layout cells API" became "Layout cell API" to match the heading below it - restrictive "which" -> "that" on line 161 Left alone, measured rather than assumed: - the nine section introductions keep their five different phrasings. There is no house majority to harmonise toward: "you can find out" runs 46 hits across 20 files, "you will learn" 32/20, "you can learn" 25/18, "you will know" 7/7. The same change was made in grid/features.md only because that page had an internal outlier confined to a single file; no such outlier exists here - "by default" inside the label "Showing a progress bar by default" stays: 40 sentence openers and 793 mid-sentence uses tree-wide - the curly apostrophe is split 13 to 7 with no rule governing it, so it was not touched as typography; the line 168 rewrite removed that possessive anyway The work list is down to that one dismissal. No heading was touched and this page has no inbound anchors. Frontmatter untouched. No link target changed. No changed line falls inside a code fence. Trailing whitespace is net zero.
Opening paragraph, all three defects local rather than templated: - "DHTMLX Layout component lets you specify" had no article before "component". The corrected form "The DHTMLX X component" appears nowhere in the tree, and sibling overviews open with the bare product name as subject, so the stray "component" was dropped instead. 0 instances of that pattern remain - "Layout helps blend diverse types of data representation" was marketing phrasing with a single occurrence tree-wide; now "helps you combine different kinds of data" - the paragraph ended with a br tag welding two sentences together, where a paragraph break belongs. Only 1 index page still does this Related resources: - "as a part of the Suite library by [downloading DHTMLX Suite]" used a by-ing link. The surrounding sentence is template across many pages and was left alone; only the link construction changed. 16 files still carry the by-ing form Guides: - "how to add Layout on the page" takes "to", not "on". The site has no instance of "add X to the page" to defer to, so the grammar rule governs. 3 files still use the wrong preposition Left alone, with reasons: - the nine empty link labels are the site convention: Docusaurus fills them with the target page title - the two trailing spaces on the Related resources item are preserved, as all incidental trailing whitespace has been in this pass - the shape of the Related resources block is shared template and not this page's to change The work list is empty after the rewrite, with no dismissals required. No heading was touched and this page has no inbound anchors. Frontmatter untouched. No link target changed. No changed line falls inside a code fence. Trailing whitespace is net zero.
- suite.js and suite.css were set in italics; api-formatting treats file names as code, so both bullets now use code formatting. 19 files across docs still carry the italic form, and calendar/how_to_start.md was already the counter-example - e.g. replaced with "for example". This was the last one in docs/layout, which now holds 0 - "place full paths to JS and CSS files of the DHTMLX Suite library" -> "place the full paths to the DHTMLX Suite JS and CSS files": a missing article and a chain of of-phrases - "The structure of a layout can be rather complex, since there can also be nested rows and columns" -> "A layout structure can be complex, because rows and columns can nest inside one another" - "a configuration object which contains" -> "that contains": the clause is restrictive - "The properties of the configuration object of Layout allow you to define the structure of Layout" -> "The properties of the Layout configuration object allow you to define its structure" - "There is also a set of properties you can specify" -> "You can also specify a set of properties" - "You will find the detailed information on configuration options of the cell object" -> "You can find detailed information on the cell object configuration options": future tense and another of-chain - "a container for the Layout" -> "a container for Layout": the page uses the zero article in every other sentence Left unchanged on purpose: - every heading, since 19 anchors across the docs point at #initialize-layout - "you need to take the following simple steps", a template shared by 18 files, matching what grid/initialization.md kept - [here] as a link label: 111 occurrences in 60 files, a site-wide habit rather than a defect of this page Verified with a docusaurus build.
14 of the 30 image descriptions on this page named a different layout than the picture shows. Checked two ways that agree: by decoding every PNG and extracting the cell rectangles, and by reading the enlarged images. Three kinds of error: - inverted. 3T, 4T, 4U and 5U claimed columns above a full-width row where the image puts the full-width row on top, or the reverse - carrying another pattern's text. 3J held the description belonging to 3T, 4I the one belonging to 4J, and 4A and 4F described shapes the images do not contain - wrong cell counts. 5K has three cells on the left and two on the right, 5S the reverse, yet both claimed two and two. 4L, 5G and 5C said one column where the image has two The pairs 3T/3U and 5K/5S were byte-identical, which is what exposed the problem. After the fix all 30 descriptions are distinct (0 duplicates) and every cell count matches the digit in the pattern name. These strings look generated from a template, so the generator is likely wrong too; this commit only fixes the page. Prose, all of it unique to this file: - "provide you with various options of arranging cells inside of a layout in a neat structure" became "let you arrange cells inside a layout": a gerund chain, the wrong form inside of, and a phrase that promises neatness without describing it - "named in accordance with their structure. Each scheme is similar to a Latin letter" became "named after their structure. Each one resembles a Latin letter". The page says pattern everywhere else, so scheme was the only occurrence of that word - "Click on the desired pattern to see its example" became "Click the desired pattern to see an example". Click on has 1 occurrence left in the docs, so it was not a house form Left alone on purpose: the desired, which appears in 38 files; every heading; and all 29 image paths and snippet links, none of which changed in the diff. Verified with a docusaurus build.
- "of cells which are placed horizontally" became "that are placed horizontally". The clause is restrictive, and line 28 of this same file already wrote "that are located vertically", so the page was inconsistent with itself - "In this layout type both rows and columns are used, i.e. a row may include several columns" became "This layout type uses both rows and columns: a row may include several columns". Drops a passive whose actor is the layout type itself and the i.e. abbreviation, which still has 19 occurrences in 18 files elsewhere. The bold on both rows and columns is unchanged - removed a trailing space at the end of line 28, the only one in the prose of this file. The one in the title on line 3 belongs to the generated frontmatter and stays Checked and deliberately left alone: - the empty link label on line 13. It is not a broken link but a site-wide macro that fills the label from the target: the built page renders it as the word rows, and the docs contain 2291 such links. Both forms are house style, so neither line 13 nor line 28 is an outlier - calling rows horizontal and columns vertical. It reads oddly next to the layout patterns page, where 2E is two stacked rows, but the text describes the orientation of each band rather than the order of the cells, and it is consistent within the page. The two API pages define only an array of rows objects, so they settle nothing - "the necessary composition of blocks", in 39 files, and "There are three common types", in 56 files: house habits, not defects here - the three single-item bullet lists. They read as subheadings, but turning them into headings would add anchors and change the sidebar, which is a structural edit rather than a wording one Verified with a docusaurus build, and the rendered page was re-checked to confirm the bold and the generated link label survived.
- "To remove a certain cell" lost certain, a vague word the style rules name outright, and "As a parameter it takes the id" became "It takes as a parameter the id". The fronted form appears 3 times in the docs against 32 for the one now used - "Use the getCell() method for this purpose" dropped the closing phrase, which says nothing the sentence has not already said - the note about Message, Popup and Window moved from the brace macro to the triple-colon form. This is NOT a rendering fix: the macro expands correctly, as the built page shows. It aligns the page with the dominant syntax, which on master stands at 465 triple-colon blocks against 135 brace ones. 123 brace notes remain in 91 files - the literals true and false moved from italics to code formatting, which leads 313 to 156 for true - a hyphen standing in for punctuation before two links became a comma; the sentence already ends in a colon, and the docs use a colon before a link 2961 times against 42 for that hyphen - "a visual component which informs users" became "that informs users", the clause being restrictive - "You may show or hide" became "You can", You may having only 10 occurrences in the docs - "can be also shown" became "can also be shown" - the last Related sample line had its colon inside the bold rather than after it, unlike the other six on the page. 61 such lines are left elsewhere - removed three trailing spaces, none of them a deliberate line break Measured and deliberately left alone, all house forms rather than defects of this page: via (416), with the help of (132), It is possible to (101), easily (68), and by default mid-sentence, which runs 793 against 45 as a sentence opener. Every heading is untouched: 25 links point at this page, most of them at its anchors. One of those headings, Attaching an HTML content to a cell, is itself ungrammatical, but correcting it would break the anchors used by features.md and by the cell detach method page, so it needs its own change together with those links. Verified with a docusaurus build, and the rendered page was checked to confirm the note became a real admonition and the two literals became code.
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.
First file outside docs/grid/ in this pass.
Typos and agreement:
Wrong verb:
collapsedproperty sets the initial state, it does not test it. Now "the second defines whether a cell is collapsed when a layout is initialized", which also drops the weak "There are two attributes of..." openerRendering:
Grammar and style:
Reported, not fixed - a genuinely broken anchor:
Left alone, each measured rather than assumed:
No heading was touched, so all 11 inbound anchors stay valid. Frontmatter untouched. No link target changed. None of the 18 changed lines falls inside a code fence. Trailing whitespace is net zero.