[update] grammar and style in Combobox and Common Features guides - #146
Open
serhiipylypchuk1991 wants to merge 13 commits into
Open
[update] grammar and style in Combobox and Common Features guides#146serhiipylypchuk1991 wants to merge 13 commits into
serhiipylypchuk1991 wants to merge 13 commits into
Conversation
serhiipylypchuk1991
commented
Sep 9, 2026
serhiipylypchuk1991
commented
Contributor
- replaced the legacy {{note}} macro with a :::note admonition, it was rendering literally on the page
- API names value, src and serialize() moved from bold to backticks, same for the key:value notation
- future tense and agentless passive rewritten as present simple with an explicit subject
- fixed articles: JSON format, id fields
- "until you use" -> "unless you apply", "on the initialization stage" -> "during initialization", "represent" -> "define"
- three sections no longer open with the same "To do X, do Y" frame, the API method now leads the sentence
- ambiguous "It" pointing at DataCollection replaced with "The method"
- three parallel serialize() conditions folded into a state table
- component name unified to Combobox, "dataset" -> "data set" in prose
- code samples: dhx.Combo -> dhx.Combobox (no such constructor exists anywhere else in docs), undefined combo1 -> combo
- replaced the legacy {{note}} macro with a :::note admonition, it was
rendering literally on the page
- API names value, src and serialize() moved from bold to backticks,
same for the key:value notation
- future tense and agentless passive rewritten as present simple with
an explicit subject
- fixed articles: JSON format, id fields
- "until you use" -> "unless you apply", "on the initialization stage"
-> "during initialization", "represent" -> "define"
- three sections no longer open with the same "To do X, do Y" frame,
the API method now leads the sentence
- ambiguous "It" pointing at DataCollection replaced with "The method"
- three parallel serialize() conditions folded into a state table
- component name unified to Combobox, "dataset" -> "data set" in prose
- code samples: dhx.Combo -> dhx.Combobox (no such constructor exists
anywhere else in docs), undefined combo1 -> combo
- replaced the legacy {{note}} macro with a :::note admonition, it was
rendering literally on the page
- API names and values moved from italics/bold to backticks: value,
multiselection, count, number, true, false
- fixed a factual slip in the Initial value list: it said "either of the
two values" and then listed three forms
- the initial value list got an intro sentence and consistent
terminators, it was hanging after the Related sample line
- "and should return a template..." was an orphaned sentence fragment
left after a bullet, folded back into a full sentence
- added the missing colon before six code samples
- "configuration property for this property" in Hidden label was a
duplicated word, the sentence is rewritten
- future tense replaced with present simple, four places
- "via" replaced with direct verbs, four places
- dropped empty sentences: "provides you with such an ability",
"This is how it can be done"
- "There is/There are", "it is possible to", "it is useful to" replaced
with active constructions
- removed filler: simply, just, If needed, Don't forget to, In order to,
make use of, In case, each time when, for this purpose
- end users -> users, from UI -> from the UI, some placeholder ->
a placeholder, options' ids -> option ids
- component name unified to Combobox
- bare "or" between two label samples replaced with a lead-in sentence
Image alt texts keep the site-wide "DHTMLX ComboBox ... in DHTMLX Suite"
pattern, and empty link labels are filled at build time, both left as is.
- fixed "a new CSS class(es)", an article paired with a plural suffix - "and should return *true/false*..." was an orphaned sentence fragment left after the parameters table, rebuilt as a full sentence - true/false moved from italics to backticks, and the passive "whether an item should be displayed" now names Combobox as the actor - <style> entity replaced with a `<style>` code span - list items capitalized and given periods, the parenthetical about including the stylesheet folded into the sentence - "There is a possibility to make changes in" and "It is possible to set" replaced with active constructions - via replaced with a direct verb, "the options of ComboBox" -> "Combobox options", "the created CSS class" -> "the class you created" - split the closing sentence about the fuzzy filter, its "in the popup list" modifier was stranded at the end, "independent of" -> "regardless of" - component name unified to Combobox The same CSS boilerplate bullet exists verbatim in 19 other */customization.md files and is deliberately left untouched there. The raw HTML parameters table with <b>/<i> is kept as is: that markup is the site-wide convention for parameter tables.
- fixed a copy-paste bug: the integration rows said "DHTMLX Chart with React/Angular/Vue" on the Combobox page; checked all 21 features.md files, only this one named a foreign component - "The example shows to load..." was missing "how", and "The example to load..." had no verb at all - "find out corresponding references of Combobox API", "Check the list of all available DataCollection API" and "perform the code after the component's rendering" rewritten, none of them parsed as English - the Clearing input row was the only table row without a leading pipe, normalized to match the rest - nine section intros used five different openings (can find out, will find out, can learn, can discover, This section explains), unified to "In this section you will learn..." - fixed broken parallelism in two intros: "how to set..., to enable..., to configure..." -> "how to set..., enable..., configure..." - "go into deep dive on its functionality" replaced, and future tense dropped from the page intro - "enable/disable the ability to..." wrappers collapsed into direct phrasing - end users -> users, via UI -> from the UI, edit/delete -> edit and delete, any operations -> all operations - missing articles added, double spaces removed, "provided by the DHTMLX library" -> "included in the DHTMLX library" - component name unified to Combobox, "look and feel" -> "appearance" to match the already updated customization page The page intro sentence is shared boilerplate across all 21 features.md files and was fixed here only, same as the CSS bullet earlier. Noticed in passing: docs/pagination/features.md:9 says "DHTMLX Message", the same copy-paste bug, left for a separate change.
- replaced the legacy {{note}} macro with a :::note admonition, it was
rendering literally on the page
- combo.events.on(), detach() and fire() moved from bold to backticks
- "The user can add... To do this, the user can use..." addressed the
reader as a third party and repeated the subject, merged into one
sentence in second person
- "any user-defined handler to any of the available events" carried two
indefinite pronouns, now "a custom handler to any available event"
- "Several handlers can be attached... will be executed" rewritten in
active present with Combobox as the actor
- "one and the same event" -> "the same event"
- "There is a simple way of removing... via the detach() method" now
leads with the method itself
- Detaching and Calling sections both opened with "To do X, ...", they
now match the Attaching section and lead with the API member
- "The names of the events" -> "Event names", table cell "name of the
event" -> "the event name"
- ComboBox -> Combobox, user-defined handler -> custom handler
The raw HTML parameters table with <b> is kept as is, per the site-wide
convention; only the descriptive cells were reworded.
- fixed a Cyrillic С (U+0421) in the placeholder value of the initialization sample, it looked identical to a Latin C but got copied into user code; the file is now ASCII apart from one em dash - "The one we have created at the previous step." was a sentence fragment, the only first-person "we" on the page and in present perfect, folded into the list item it belonged to - "Detailed information ... is given in the [] article" turned active - the page intro and the Initialize section both opened with "To do X, do Y", the second one just restating its own heading - suite.js and suite.css moved from italics to backticks, and "combo_container" from straight quotes to a code span - wrong prepositions: add ... in your application -> to, at the previous step -> in, as a part of -> as part of - "a folder of your project" -> "your project folder", "into the header of the file" -> "in its header" - removed padding: you need to follow, you should use, After that, "constructor function" -> "constructor", "the object constructor" -> "the constructor" - capitalized the two constructor parameter list items - added the missing period in the :::info block - component name unified to Combobox, including the Initialize and Load data headings; their anchors are unchanged, so the in-page links from the steps list still resolve
- rewrote the intro paragraph: "provides the ability to show suggestions" -> "shows suggestions", present continuous -> present simple, "specify templates of displaying options" reworded - "Among other nice features there are tuning of..., selection of... and data loading on request" dropped the editorial "nice", the there-are construction and three gerund nouns, and gained the missing serial comma - removed a mid-sentence hard wrap with a trailing space - the three Related resources bullets had three different shapes (statement, "There are also", inversion), now parallel imperatives - "as a part of" -> "as part of", "by [downloading DHTMLX Suite]" now leads with the link, "To work with data of ComboBox check" was missing its comma and became "Check the [DataCollection API] to work with Combobox data" - "You can check the following page" -> "Check the following page" - component name unified to Combobox, including the H1; its anchor combobox-overview is unchanged The Features lead-in and the Related resources bullets are shared boilerplate across all index.md files (List has them verbatim) and were fixed here only, same as the earlier pages in this branch. This page has no code samples.
- fixed the setLocale sample: it passed the DOM container id
("combo_container") where the method expects a widget name. Every
other page uses setLocale("form"/"calendar"/"grid"/"colorpicker", de),
and grid/configuration.md:1185 uses setLocale("combobox", locale) for
this very component, so the sample as written would not localize
- fixed the typo "To use a different locale, your need to:"
- that same line was a list intro the items had to finish
grammatically, replaced with "Follow these steps to use a different
locale:"
- dhx.i18n.setLocale() moved from bold to backticks
- both list items capitalized and turned into parallel imperatives, the
"by calling" link dropped
- the hyphen used as a parenthetical dash replaced with an em dash,
"names of buttons and labels" -> "button and label names"
- removed padding: just, corresponding, necessary; "a ready locale" ->
"the resulting locale"
- "the interface of DHTMLX Combo" -> "the DHTMLX Combobox interface",
"looks like this" -> "uses the following default locale"
The German sample strings are untouched, but two of them read oddly:
createItem is "Schaffen" rather than "Erstellen", and unselectAll is
"Deaktivieren Sie Alle" while selectAll next to it is "Alle auswählen".
That is a translation call, not a grammar one.
- parameter names and types moved from bold/italics to backticks, with the hyphen separator replaced by an em dash - method link labels were split between [setValue()] and [`paint()`], all nine unified to backticks; that form is the more common site convention (128 files against 66) and is what api-formatting requires - eight paragraphs in a row opened with "To do X, do Y", each restating its own heading; they now lead with the method or event - "e.g." -> "for example", "by default" -> "the default return type is" - "It takes two parameters" pointed at Data Collection rather than the method, twice, now "The method takes" - "Pass the id of the option that should be removed to the method" stranded its modifier and used passive, now "Pass the option id" - "It is possible to clear/add" replaced with active constructions - "with the help of" dropped in three places - removed padding: In order to, make use of, for this purpose, When needed, the process of showing/hiding, the corresponding methods - "prevent showing/hiding of a popup" -> "prevent the popup from opening/closing", "for adding" -> "to add" - via -> with, restrictive "which" -> "that" - fixed prepositions and of-chains: clear the selected values from the input, add options to an initialized Combobox, "config options of the option" -> "option settings" - ComboBox/Combo/combobox -> Combobox, ID(s)/IDs -> ids, "Data collection API" -> "Data Collection API", For instance -> For example Section headings are untouched: features.md links to their anchors (#disablingenabling-combobox, #hidingshowing-the-popup and others). The H1 is left as is so it keeps matching sidebar_label. HTML tables keep their <b>/<i> markup per the site convention; only cell wording changed.
- resolved a contradiction in the Grid section: roles and attributes were marked "(enabled by default)" while the next sentence said there is no flag to disable them - fixed a Cyrillic С (U+0421) in "High-Сontrast Themes"; the file now has no non-ASCII left apart from em dashes - fixed "There are general description of the component" (subject-verb disagreement) and the missing period in "are enabled by default You can find", both duplicated in List/DataView and Toolbar - fixed the dangling participle "Being rather attractive, it is also helpful", where "it" had no antecedent - "users that are visually impaired" -> "who", and the Enter key bullet was missing the word "key" that its three siblings had - ARIA role and attribute values moved from italics to backticks, and pointType from bold to backticks - "3 levels of conformance; A, AA and AAA" used a semicolon where a colon belongs, repeated "conformance" three times and lacked the serial comma - passive constructions rewritten with a named actor: care should be taken, information is taken from, the ability is not provided, you are not mandated to conform, are provided with keyboard navigation support - "Role presentation and aria-hidden are used to hide" (4 occurrences) -> "The presentation role and aria-hidden hide" - three of four keyboard bullets were passive while the fourth was active; all four are active now and capitalized - "presupposes equal access" -> "gives equal access", "provides support for" -> "supports", "WCAG 2.0 standards" -> singular - removed padding: Currently, most commonly encountered, the guidelines outlined, Among various themes there are, four "There are" openers - hyphen separators in the standards list -> em dashes, "web based" -> "web-based", missing serial commas, stray double space and a trailing space in the Toolbar heading Not changed, flagged instead: line 40 lists aria attributes with mixed naming, some without the aria- prefix (label, rowcount, colcount, rowindex, colindex) and some with it. That is a factual question about the attribute names, not a grammar one. Headings are untouched, the page links to their anchors itself.
- replaced the legacy {{pronote}} macro with a :::info admonition, it
was rendering literally on the page, and added the missing article in
"requires the PRO version"
- dropped "i.e." per the abbreviations rule and rewrote the passive
"they are initially hidden and shown only when the user hovers"
- removed the comma in "You may notice, that all DHTMLX demos", a comma
before that in an essential clause, along with the filler opener
- enable, dhx.scrollViewConfig, true, enable() and scrollView moved from
bold/italics to backticks
- the bare lowercase "or" between two code samples replaced with a lead
in naming the second option
- dropped the editorial "neat", "add the feature into your application"
-> "to", "you need to set" -> "set", "before initialization of the
widgets" -> "before you initialize the widgets"
- "read [this article]" -> a link labeled with the target article
- the Related article column repeated "learn more in the related
article" in all seven cells, which restated the column header and gave
seven links the same text; cells now carry named links, targets
unchanged
- added the missing "and" in the component list, removed three trailing
spaces
Two things left for a decision, not changed here:
- the demo URLs look shifted. dhtmlxFileExplorerDemo is used twice, for
File Explorer (correct) and UI Dashboard, while Hotel Management
Template points at dhtmlxDashboard. Guessing the right targets is not
a grammar call.
- {{pronote}} also appears in pagination/index.md, form/container.md,
list/load_data.md, helpers/lazydataproxy.md, helpers/datadrivers.md,
helpers/custom_scroll.md and grid/data_loading.md, all rendering as
plain text. Fixed here only, as with the earlier boilerplate.
- "Since version 7.0 and upper" is not a construction that exists;
replaced with "From v7.0", the phrasing used elsewhere in the docs
- fixed the dangling modifier in "While interacting with applications by
touching the screen, a tap becomes...", where the implied subject was
the user but the main clause subject was the tap
- removed the comma in "But note, that the mouseover events...", a comma
before that in an essential clause
- "the click events (fire on clicking, double clicking an item)" did not
parse as a sentence and lacked a conjunction
- added the missing "and" between the two purposes in the Drag bullet
- replaced the legacy {{note}} macro with a :::info admonition, and the
raw <a target="_blank"> inside it with a markdown link; Docusaurus adds
the target attribute to external links itself
- hyphen separators in the gesture list -> em dashes
- "provides the built-in Touch support that should work out of the box"
carried "provide", a stray article, a capitalized Touch mid-sentence
and a banned phrase; now "includes built-in touch support"
- "comfy" -> "comfortable", dropped the "As a result," and "Thus,"
openers, future tense -> present
- "enables recognition for the following touch gestures" -> "recognizes
the following gestures", which also drops the third "touch" in two
sentences
- removed a stray article and a trailing space
Not changed: "the dhtmlxSuite library" is a legacy spelling of the
product name in 16 files (sidebar/initialization.md, pagination/init.md,
data_proxy/index.md and others). Normalized to DHTMLX Suite here only,
as with the earlier shared boilerplate.
- fixed "much easier, safety, and productive", a noun in a list of
adjectives, and "all modern IDE" missing its plural
- fixed "Typescript" on line 13, the only occurrence of that spelling in
the whole docs tree; the same page spells it TypeScript four times
- the page jumped from # straight to ###; promoted the section to ##.
Nothing links to its anchor and the slug is unchanged
- replaced the legacy {{note}} macro with a :::info admonition and the
raw <a target="_blank"> inside it with a markdown link
- lines 9 and 13 said the same thing twice; the first now covers the
definitions, the second the absence of setup
- "provides a built-in support of Typescript that should work out of the
box" carried "provide", a wrong article and preposition, a banned
phrase and a hedging "should"
- "by using TypeScript definitions" link removed by making the
definitions the subject of the benefit
- fixed articles: the app development, a more stable code
- dropped the "Moreover," opener and the "therefore" aside, future tense
-> present, "help you to avoid" -> "help you avoid"
- "Checking the types together with autocompletion" -> "Type checking
and autocompletion", "your code created with DHTMLX" -> "the DHTMLX
code you write"
- removed trailing spaces on three lines
Not changed: "The dhtmlxSuite library" is the same legacy product
spelling found in 16 files. Normalized here only, as with the earlier
shared boilerplate.
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.