Documentation revision (./docs/*.md files)

[Anirban166]

Originating Project/Creator	@Anirban166
Affected Component	N/A
Affected Architectures(s)	N/A
Related Issue(s)	-/-
Has Unit Tests (y/n)	n
Builds Without Errors (y/n)	y
Unit Tests Pass (y/n)	y
Documentation Included (y/n)	y

---

Change Description

Includes corrections for typographical errors and edits for better semantics and grammar for the content in the markdown files located in the docs directory.

While reviewing, I found a few paragraphs where the sentence structure is ambiguous. Among those, I fixed/rephrased the ones which I could understand well, but there are sections where I couldn't strictly determine what the original author(s) intended to say and so I left them unchanged.

Rationale

To keep the documentation free of typos and to improve readability in general.

Testing/Review Recommendations

I'm a bit concerned about this not being a small change (in size, across files) to review. I thought of going for a single PR instead of multiple ones since it might have been immaterial to do the latter, given that these changes involve no code (but are still subtly significant) and have patterns. Let me know if this needs to be segregated or decomposed into smaller PRs though, or if there is anything else I could help with regards to improving the documentation firsthand!

Future Work

• #1251 perhaps

[LeStarch]

I'll be honest this is a big one to review. Since it is all .md files (no code), I'll review it as is (no need to break it up). It might take some time.

[Anirban166]

I'll be honest this is a big one to review. Since it is all .md files (no code), I'll review it as is (no need to break it up). It might take some time.

I agree! It felt like a lot of scrolling after I saw the 'Files changed' section post submission of this PR. Thank you for taking the time to review this! (also @skovati!)

[github-actions[bot]]

@check-spelling-bot Report

:red_circle: Please review

See the :open_file_folder: files view or the :scroll:action log for details.

Unrecognized words (37)

aniso
binaryornot
Brotli
certifi
chardet
configs
dateutil
deserializes
fds
filesystems
gcovr
gnd
hyperlinks
idna
importlib
iniconfig
inttype
itsdangerous
PNGs
poyo
ptyprocess
PYS
pytests
pytz
pyzmq
regexs
Tful
toolchains
tts
Ubuntu
UML
unidecode
Watney
Werkzeug
Whitelisted
xmls
zipp

Previously acknowledged words that are now absent

aadl aarondou Accu adoc alignedallocator apps argparse args arity asciidoctor aspx autocomplete autodetect autogenerated autogenerator autonumbering awt bavail bbd bc bithacks BLSP bootup bw bytearray capout cfg checkbox chmod chown chr ci cinttypes Classloader classmethod classpath compat componentaction compositestructures compxml concat config configurator cpp cpy creatingdocsetswithdoxygen css csv cxx datetime delattr deserialize deserializer DHTML Dinstall dll doall dockerfile Donatas donsim Doubek dropdown ecore elif endfor endif endswith eps errstr esac etree ev exe fd fh filesystem foundin fprim FPRIMEPROTOCOL func functools gainsboro getattr getcwd getenv gethostbyname getmtime getpass getppid gettempdir gh globals gmail Gnd GNDIF groupadd groupmod GTestbase gz hasattr hdp hh HOMEPAGE hostent hpp href htm html http hu HWriter hxx hyperlink hz ifchange IFXML IJET img includefile ini inl ino inorder INSTALLDIR instanceof interoperability Inttype ip isabs isdir isfgen isfile isfpluginexec isfxmlwriter isinstance issubclass itcl iu javabuilder javac javanature javascript javax jdt jf JFile jmi JOption jpg json junit kevensen len lifecycle lightgreen lightyellow listdir ljust localtime longdesc lstrip lte magicdraw mailto makedirs mcternan mdbasiccomponents mdinternalstructures mdkernel mdports mdprofiles mdxml mdzip memoization memoize metadata middleware mkdir mname mngr mpmcs mq mscgen MTIME multiline MVC Mypy namespace nargs nasafprime nbsp netdb Netscape's NGAT nh nio nomagic nondetached nroff OMG's onchange openjdk orangered OS'es overridable ovrTrace pdf peeker perl php phtml placeholders PLUGINDIR png posix ppid Prepends println proj propvals PROTOCOLINTERFACE py Pymodule PYPI pytest PYTHONPATH pyw quickstart rb readline refman regex RHEL rmdir rmtree rng RPISCHEDCONTEXTS rstrip rtf rx saikiranra seander setattr shutil Simkunas SOCKETIPDRIVERTYPES splitext splitlines SQL's sramanan startswith startword staticmethod strcat strcpy strftime Stringify structs stylesheet submenu svg sys tcl td templating testhpp Testname textui timezone tkgui tl tmp tmpd tmpdir tmpl toc toclevels toolbar toolchain tooltip tt tz ubuntu uk ul uml url urllib useradd usermod utc utils uuid ve virtualenv vm vmsize vn vue vx watney whitelist workaround workspaces wp writelines wx xhtml xls xlsx xml xmlns Xmx Xss Xvfb yml zsh zu

Some files were automatically ignored

These sample patterns would exclude them:

^\QFw/Types/Linux/StandardTypes.hpp\E$

You should consider adding them to:

.github/actions/spelling/excludes.txt

File matching is via Perl regular expressions.

To check these files, more of their words need to be in the dictionary than not. You can use patterns.txt to exclude portions, add items to the dictionary (e.g. by adding them to allow.txt), or fix typos.

To accept :heavy_check_mark: these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the [email protected]:Anirban166/fprime.git repository on the devel branch (:information_source: how do I use this?):

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
(cat '.github/actions/spelling/excludes.txt' - 2> /dev/null <<EOF
$should_exclude_patterns
EOF
) |grep .|
sort -f |
uniq > '.github/actions/spelling/excludes.txt.temp' &&
mv '.github/actions/spelling/excludes.txt.temp' '.github/actions/spelling/excludes.txt'
}

comment_json=$(mktemp)
curl -L -s -S \
-H "Content-Type: application/json" \
"https://api.github.com/repos/nasa/fprime/issues/comments/1196978618" > "$comment_json"
comment_body=$(mktemp)
jq -r ".body // empty" "$comment_json" | tr -d "\\r" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")

patch_add=$(perl -e '$/=undef; $_=<>; if (m{Unrecognized words[^<]*</summary>\n*```\n*([^<]*)```\n*</details>$}m) { print "$1" } elsif (m{Unrecognized words[^<]*\n\n((?:\w.*\n)+)\n}m) { print "$1" };' < "$comment_body")

should_exclude_patterns=$(perl -e '$/=undef;
$_=<>;
exit unless s{(?:You should consider excluding directory paths|You should consider adding them to).*}{}s;
s{.*These sample patterns would exclude them:}{}s;
s{.*\`\`\`([^`]*)\`\`\`.*}{$1}m;
print' < "$comment_body" | grep . || true)

update_files
rm $comment_body
git add -u

Warnings (2)

See the :open_file_folder: files view or the :scroll:action log for details.

:information_source: Warnings	Count
:information_source: limited-references	1
:information_source: noisy-file	1

See :information_source: Event descriptions for more information.

If the flagged items are false positives

If items relate to a ...

• binary file (or some other file you wouldn't want to check at all).

  Please add a file path to the excludes.txt file matching the containing file.

  File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

  ^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

• well-formed pattern.

  If you can write a pattern that would match it, try adding it to the patterns.txt file.

  Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

  Note that patterns can't match multiline strings.