Improve and update style guide based on @ccordoba12 feedback

STYLEGUIDE.md

@@ -16,9 +16,9 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 
 - In general, follow the [OpenStack Heading Guidelines](https://docs.openstack.org/doc-contrib-guide/writing-style/general-writing-guidelines.html) with regard to sections and headings; in particular, section and subsection titles delineating overall categories of tasks/topics and be in gerund (i.e. with "ing", e.g. "Editing code", "Debugging files"), while those concerning a concept or reference topic should be a noun (e.g. "General considerations", "Requirements") and lowest level topic/task titles should generally be in imperative ("Create a code cell", "Get help", etc) where reasonable
 - Heading case: Page titles (L1 headings) should use Title Case, all others should use Sentence case
-- 1 L1 Heading for page titles: Use ``######`` with overline; on first line of file; keep to a few words
+- One L1 Heading, used for page titles: Use ``######`` with overline; on first line of file; keep to a few words
 - L2 Headings for section heads: Use ========= with overline; 3 blank lines before them, will appear in sidebar so keep them short
-- L3 headings for subheads: Use ~~~~~~, 2 blank lines,
+- L3 headings for subheads: Use ~~~~~~, 2 blank lines
 - L4 Headings for sub-subheads if truly necessary: Use ---------, 2 blank lines, keep to a minimum (consider a flatter structure or breaking into multiple files)
 - Related components at the bottom: L3 heading, bullets, 2 blank lines before, try for 2-4 links if included
 - All files with Related components should contain at least one L2 section; if only one, can be  entitled Overview
@@ -37,7 +37,7 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 - 1 blank line after all headings and before and after paragraphs, directives and "|"s
 - Use Line Feed (LF, ``\n``) as the End of Line character on all platforms
 - Use UTF-8 for all files (with no BOM, as dictated by the UTF-8 standard); do not use Windows Notepad as this adds a BOM and can otherwise corrupt files easily
-- Indicate special characters (e.g. em dash, en dash, etc) by simply including them inline with Unicode
+- Use standard UTF-8 characters instead of escape sequences for non-ASCII values (e.g. em dash, en dash, etc)
 - Suggested to avoid non-ASCII characters where minimal downside/need exists, and recommended to keep used characters within the Latin-1 set where an additional range is not required by the specific usage, or an existing proper name or other identifier uses them
 - Spaces, no tabs for indentation and otherwise
 - Natural indents (3 spaces) for directives, 4 spaces for further indents beyond that in code
@@ -52,14 +52,14 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 
 ## reST Style Elements
 
-- Filenames/paths: Use :file: and ``/`` for deliminators e.g. :file:`path/to/test.py`. Example filenames should be all lowercase with no spaces or special characters unless called for by the application; real filenames should follow their actual case. Use {descriptive-name} for placeholders.
-- Keyboard Shortcuts: Use :kbd: to format, Ctrl/Alt/Shift as abbreviations (instead of Command/Option), ``-`` with no spaces to separate, and title case (including capital letters for letter keys; always include Shift explicitly if needed) e.g. :kbd:`Ctrl-Alt-Shift-P`. Use the key name or symbol as printed on a standard keyboard. For any configurable shortcut, you should include "by default" to indicate this, and must include at least one another means the command can be accessed if available (e.g. via a menu or toolbar), which should be done for all shortcuts and should include all means of executing the command, if multiple others exist.
-- GUI elements (names of things in the UI): Use ``:guilabel:`` , e.g. ``:guilabel:`Name```; make sure to use the exact name and capitalization as printed in the UI, except for the proper names of Spyder panes (i.e. those listed in the ``View > Panes`` menu), which should always be written in Title Case ("History Log", "Project Explorer", "Find in Files", etc. as they are proper names). Also, for consistency and clarity, they should be referred to as panes, rather than modules, plugins, panels, etc.; Find in Files may be called a "tool" if appropriate to the context.
-- Menu items and preference panes: Use :menuselection: to format and ``-->`` to separate, e.g. `` :menuselection:`Project --> New Project` ``, make sure to use the exact name and capitalization of each level element
+- Filenames/paths: Use :file: and ``/`` for delimiters e.g. :file:`path/to/test.py`. Example filenames should be all lowercase with no spaces or special characters unless called for by the application; real filenames should follow their actual case. Use {descriptive-name} for placeholders.
+- Keyboard Shortcuts: Use :kbd: to format, Ctrl/Alt/Shift as abbreviations (instead of Command/Option), ``-`` with no spaces to separate, and title case (including capital letters for letter keys; always include Shift explicitly if needed) e.g. :kbd:`Ctrl-Alt-Shift-P`. Use the key name or symbol as printed on a standard keyboard. For any configurable shortcut, you should include "by default" to indicate this, and must include at least one other means the command can be accessed if available (e.g. via a menu or toolbar), which should be done for all shortcuts and should include all means of executing the command, if multiple others exist.
+- GUI elements (names of things in the UI): Use ``:guilabel:`` , e.g. ``:guilabel:`Name` ``; make sure to use the exact name and capitalization as printed in the UI, except for the proper names of Spyder panes (i.e. those listed in the ``View > Panes`` menu), which should always be written in Title Case ("Variable Explorer", "Code Analysis", "IPython Console", etc. as they are proper names). Also, for consistency and clarity, they should be referred to as panes, rather than modules, plugins, panels, etc.; Find in Files may be called a "tool" if appropriate to the context.
+- Menu items and preference panes: Use :menuselection: to format and ``-->`` to separate, e.g. `` :menuselection:`Project --> New Project` ``. Make sure to use the exact name and capitalization of each level element
 - Short commands/lines of code (under 20-30 characters), use `` , e.g. ``code``
 - For any code longer than one line, ~20-30 characters, or that is otherwise important to emphasize rather than just mention, use ``code-block::`` tags, closed with ``end``, and specify the programming language (bash for command line, python for python, ini for configuration files, etc.). PEP 8 should be followed for Python code, with all "recommended"/"preferred"/"suggested" guidelines being treated as *should* i.e. only broken with appropriate justification in a situation requiring them; similarly, PEP 257 for docstrings where needed. Additionally, all code must be valid and idiomatic Python 3 unless specifically meant to illustrate a distinction with Python 2, and code should for the time being fall under the common subset supported by Spyder's supported platforms (currently, Python 2.7 and Python 3.4-3.6). Wrap code blocks at a width of 70 characters from the page margin for readability.
 - Internal links to sections should never rely on implicit references, since they may change with section titles or other re-organization. Instead, always use explicit references above the target with one blank line between; keep ref names short, use ``-`` to replace spaces, use unique and distinctive names and append ``-ref`` to the end of the name for clarity.
-- All external links should be inline (not bare) unless specifically needed to illustrate some property of the link itself, should be https if available, and should, generally, be written as a reference with `` `Test Link Name`_ `` and then included in full at after the end of the paragraph in which it appears, e.g. `` .. _Test Link Name: https://www.example.com/ `` . A block of links should be separated from paragraphs above and below by one blank line, with no blank lines between links. Make sure to check that your links, as the build will automatically check for broken ones. Strip anything unnecessary (parameters, referrers, etc) off the end. As the base docs are in US English, any links should be to the English, desktop version of the site.
+- All external links should be inline (not bare) unless specifically needed to illustrate some property of the link itself, should be HTTPS if available, and should, generally, be written as a reference with `` `Test Link Name`_ `` and then included in full after the end of the paragraph in which it appears, e.g. `` .. _Test Link Name: https://www.example.com/ `` . A block of links should be separated from paragraphs above and below by one blank line, with no blank lines between links. Make sure to check your links, as the build will automatically check for broken ones. Strip anything unnecessary (parameters, referrers, etc) off the end. As the base docs are in US English, any links should be to the English, desktop version of the site.
 - Use enumerated lists with ``#. `` to list items with a clearly defined order, otherwise, use bulleted lists with ``* ``. Include a space between the bullet/number and the text. No blank line between elements, unless a sublist is present, but blank lines around the list. Sublist should have no spaces around elements. You should try to avoid more than two levels of lists if at all possible, and keep lists to between 3 and 10-20 elements; anything shorter should be written in prose, and anything longer should be simplified or broken into multiple lists/sublists.
 - Use ``note::`` for general callouts, ``warning::`` to warn users against procedures with potential serious consequences, and ``important::`` for key points that users don't want to miss. However, use these sparingly, only when clearly called for. Always make them separate blocks, with a blank line between the start of the block, like:
 ```
@@ -70,7 +70,6 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 
 ## Images/Figures
 
-- Organize images into directories following the Google drive
 - Lower case file names and extensions, separate with hyphens, 3-character extensions
 - For ease of visibility, explanatory images should be full width; expository or those with very simple subjects can be half-width, right aligned
 - Use PNG for all images, except photographs over 100-200 KB as a PNG (use moderately compressed JPEG); avoid sizes above 2000 x 2000 or below 1000 x 1000 if full width, or half of each if half width
@@ -84,7 +83,7 @@ Must (not), should (not), recommended, suggested, may, and can generally follow
 - Maintain an explanatory rather than expository tone if appropriate for the language (i.e. in English, "How" rather than "What"; e.g. "Spyder can do XXX." -> "To do XXX, you can...")
 - Focus on the user; this is documentation, not promotional material
 - Try to use simple language if possible and avoid buzzwords, jargon and acronyms
-- Make sure capitalization, spacing etc. of proper names and acronyms are correct and consistent per the original (or the canonical localized form is availible)
+- Make sure capitalization, spacing etc. of proper names and acronyms are correct and consistent per the original (or the canonical localized form if available)
 - In text, use the full name for file types ("TIFF" and "JPEG", not "TIF" and "JPG"), and always use ``/`` as the path delimiter
 - Must use ISO 8601 (YYYY-MM-DD HH:MM:SS, 24-hour format, with leading zeros) for all numeric dates and times. No convention is imposed for textual forms (e.g. January 1, 2018; 1 de abril de 2019; etc) so long as all three components are provided, the month names are written out in full, and the year is written as 4 digits.
 -  ``.`` must be used as the decimal separator in languages that at least partially use it (i.e. a native speaker would not be unfamiliar with its use), and suggested otherwise at the option of the translator to be consistent with its use in Python and  internet standards, and avoid the textual ambiguity of `,`; regardless of which is chosen, it is more important to use it consistently throughout the docs of a given language