Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor style updates related to UNIX #163

Merged
merged 1 commit into from
Mar 9, 2022
Merged

Minor style updates related to UNIX #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions supplementary_style_guide/glossary_terms_conventions/general_conventions/e.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
[discrete]
[[emacs]]
==== image:images/yes.png[yes] Emacs (noun)
*Description*: "Emacs" is a text editor available in Unix. Like vi, Emacs is a screen editor. Unlike vi, Emacs is not an insertion mode editor, meaning that any character typed in Emacs is automatically inserted into the file, unless it includes a command prefix.
*Description*: "Emacs" is a text editor that is available on the UNIX system and similar operating systems. Like vi, Emacs is a screen editor. Unlike vi, Emacs is not an insertion mode editor, meaning that any character typed in Emacs is automatically inserted into the file, unless it includes a command prefix.

If referring to the program, use "Emacs," for example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use `emacs`. Always mark up the command correctly, for example, "At the prompt, type `emacs`." The complete and correct name is "GNU Emacs."

*Use it*: yes

*Incorrect forms*:
*Incorrect forms*:

*See also*:

Expand All @@ -29,7 +29,7 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Use it*: yes

*Incorrect forms*:
*Incorrect forms*:

*See also*: xref:return[return]

Expand All @@ -40,20 +40,20 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Use it*: with caution

*Incorrect forms*:
*Incorrect forms*:

*See also*: xref:subscription[subscription], xref:repository[repository]

[discrete]
[[environment]]
==== image:images/yes.png[yes] environment (noun)
*Description*: In IT, "environment" refers to the state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, when one speaks of running a program in a Unix "environment," it means running a program on a computer that has the Unix operating system. One ingredient of an environment is the operating system, but operating systems include a number of different parameters. For example, many operating systems allow you to choose your command prompt or a default command path. All these parameters taken together comprise the environment.
*Description*: In IT, "environment" refers to the state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, when one speaks of running a program in a UNIX "environment," it means running a program on a computer that has the UNIX operating system. One ingredient of an environment is the operating system, but operating systems include a number of different parameters. For example, many operating systems allow you to choose your command prompt or a default command path. All these parameters taken together comprise the environment.

*Use it*: yes

*Incorrect forms*:
*Incorrect forms*:

*See also*:
*See also*:

[discrete]
[[essentially]]
Expand All @@ -62,9 +62,9 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Use it*: no

*Incorrect forms*:
*Incorrect forms*:

*See also*:
*See also*:

[discrete]
[[event]]
Expand All @@ -73,7 +73,7 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Use it*: yes

*Incorrect forms*:
*Incorrect forms*:

*See also*:

Expand All @@ -95,7 +95,7 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Use it*: yes

*Incorrect forms*:
*Incorrect forms*:

*See also*:

Expand All @@ -108,14 +108,14 @@ If referring to the program, use "Emacs," for example, "Source-Navigator support

*Incorrect forms*: EXIF, exif

*See also*:
*See also*:

[discrete]
[[extranet]]
==== image:images/yes.png[yes] extranet (noun)
*Description*: "Extranet" refers to an "intranet" that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to people who are members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password. Your identity determines which parts of the extranet you can view.

Capitalize "extranet" only at the beginning of a sentence.
Capitalize "extranet" only at the beginning of a sentence.

*Use it*: yes

Expand Down
8 changes: 4 additions & 4 deletions supplementary_style_guide/glossary_terms_conventions/general_conventions/g.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@
[discrete]
[[gdb]]
==== image:images/yes.png[yes] GDB (noun)
*Description*: "GDB" is an acronym for "GNU Debugger," the standard debugger for the GNU operating system. It is a portable debugger that runs on many Unix-like systems and works for many programming languages. When referring to the program, use "GDB."
*Description*: "GDB" is an acronym for "GNU Debugger," the standard debugger for the GNU operating system. It is a portable debugger that runs on many operating systems that are similar to the UNIX system, and works for many programming languages. When referring to the program, use "GDB."

*Use it*: yes

Expand All @@ -123,7 +123,7 @@
[discrete]
[[gdb-command]]
==== image:images/yes.png[yes] gdb (noun)
*Description*: "GDB" is an acronym for "GNU Debugger," the standard debugger for the GNU operating system. It is a portable debugger that runs on many Unix-like systems and works for many programming languages. When referring to the command, use `gdb`, marked up appropriately.
*Description*: "GDB" is an acronym for "GNU Debugger," the standard debugger for the GNU operating system. It is a portable debugger that runs on many operating systems that are similar to the UNIX system, and works for many programming languages. When referring to the command, use `gdb`, marked up appropriately.

*Use it*: yes

Expand Down Expand Up @@ -178,7 +178,7 @@
[discrete]
[[gnome]]
==== image:images/yes.png[yes] GNOME (noun)
*Description*: "GNOME" is an open source desktop environment for Unix systems.
*Description*: "GNOME" is an open source desktop environment for operating systems that are similar to the UNIX system.

*Use it*: yes

Expand All @@ -200,7 +200,7 @@
[discrete]
[[gnu]]
==== image:images/yes.png[yes] GNU (noun)
*Description*: "GNU" is a recursive acronym for "GNU's Not Unix." GNU is a Unix-like, open-source operating system. Do not use "Gnu" or "gnu."
*Description*: "GNU" is a recursive acronym for "GNU's Not UNIX." GNU is an open-source operating system that is similar to the UNIX system. Do not use "Gnu" or "gnu."

*Use it*: yes

Expand Down
2 changes: 1 addition & 1 deletion supplementary_style_guide/glossary_terms_conventions/general_conventions/j.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
[discrete]
[[jsvc]]
==== image:images/yes.png[yes] jsvc (noun)
*Description*: The Apache Commons Daemon "jsvc" is a set of libraries and applications for making Java applications run on Unix more easily. Capitalize the initial "J" only at the beginning of a sentence.
*Description*: The Apache Commons Daemon "jsvc" is a set of libraries and applications for making Java applications run on UNIX systems more easily. Capitalize the initial "J" only at the beginning of a sentence.

*Use it*: yes

Expand Down
2 changes: 1 addition & 1 deletion supplementary_style_guide/glossary_terms_conventions/general_conventions/l.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
[discrete]
[[linux]]
==== image:images/yes.png[yes] Linux (noun)
*Description*: "Linux" is a Unix-like operating system. Do not use "LINUX" because it is not an acronym. Do not use "linux" unless you are referring to a command, such as "To start Linux, type `linux`." In that case, mark it correctly.
*Description*: "Linux" is an operating system that is similar to the UNIX system. Do not use "LINUX" because it is not an acronym. Do not use "linux" unless you are referring to a command, such as "To start Linux, type `linux`." In that case, mark it correctly.

*Use it*: yes

Expand Down
2 changes: 1 addition & 1 deletion supplementary_style_guide/glossary_terms_conventions/general_conventions/p.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@
[discrete]
[[posix]]
==== image:images/yes.png[yes] POSIX (noun)
*Description*: "POSIX" is an acronym for "Portable Operating System Interface [for Unix]."
*Description*: "POSIX" is an acronym for "Portable Operating System Interface [for UNIX]."

*Use it*: yes

Expand Down
4 changes: 2 additions & 2 deletions supplementary_style_guide/glossary_terms_conventions/general_conventions/r.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
[discrete]
[[raw]]
==== image:images/yes.png[yes] raw (adjective)
*Description*: In computing terms, "raw" means unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, "cooked" refers to data that is processed before being passed to the I/O device. The term comes from Unix, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device.
*Description*: In computing terms, "raw" means unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, "cooked" refers to data that is processed before being passed to the I/O device. The term comes from the UNIX system, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device.

*Use it*: yes

Expand Down Expand Up @@ -335,7 +335,7 @@ Write this name in full the first time that you use it in a document. Subsequent
[discrete]
[[runlevel]]
==== image:images/yes.png[yes] runlevel (noun)
*Description*: A "runlevel" is a preset operating state on a Unix-like operating system. A system can be booted in to (that is, started up in to) any of several runlevels, each of which is represented by a single-digit integer. Each runlevel designates a different system configuration and allows access to a different combination of processes (that is, instances of executing programs). There are differences in the runlevels according to the operating system. Seven runlevels are supported in the standard Linux kernel.
*Description*: A "runlevel" is a preset operating state on a UNIX system and similar operating systems. A system can be booted in to (that is, started up in to) any of several runlevels, each of which is represented by a single-digit integer. Each runlevel designates a different system configuration and allows access to a different combination of processes (that is, instances of executing programs). There are differences in the runlevels according to the operating system. Seven runlevels are supported in the standard Linux kernel.
Copy link
Contributor

@ndeevy ndeevy Mar 1, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fab improvements here @bredamc!

This comment is not part of your changes so feel free to ignore if it's beyond scope, but I wonder could we improve the second sentence, it seems unnecessarily clunky and troublesome for translation. Mainly because of the parentheses and the verb+preposition weirdness of ' started up in to'. Could probably avoid the word 'boot' altogether anyway. I don't think it'd change the meaning detrimentally to simplify it to something like:

You can start a system into several runlevels, each of which is represented by a single-digit integer.

could replace the second set while we're there too:

Each runlevel designates a different system configuration and allows access to a different combination of instances of executing programs.

Copy link
Contributor Author

@bredamc bredamc Mar 2, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much for your review, @ndeevy! I agree that the entire paragraph could use an edit, but I think it might be better to edit in a separate PR? I don't have enough expertise in this particular area so it would require significant review, which might delay the current PR. For example, is the system booted in several (or one of several) runlevels? Also, I think "processes" might be the better understood term, rather than "instances of executing programs". And is "allows" the correct verb here, or would "provides" be sufficient (not sure whether permissions are involved)? So many questions :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bredamc yeah, you're so right. It's potential can of worms territory. I can try fix it down the road so as not to delay this PR's changes being merged ;-]


*Use it*: yes

Expand Down
2 changes: 1 addition & 1 deletion supplementary_style_guide/glossary_terms_conventions/general_conventions/s.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
[discrete]
[[samba]]
==== image:images/yes.png[yes] Samba (noun)
*Description*: "Samba" is a freeware program that allows end users to access and use files, printers, and other commonly shared resources on a company's intranet or on the internet. Samba can be installed on a variety of operating system platforms, including Linux, most common Unix platforms, OpenVMS, and OS/2.
*Description*: "Samba" is a freeware program that allows end users to access and use files, printers, and other commonly shared resources on a company's intranet or on the internet. Samba can be installed on a variety of operating system platforms, including Linux, most common UNIX platforms, OpenVMS, and OS/2.
Amrita42 marked this conversation as resolved.
Show resolved Hide resolved

*Use it*: yes

Expand Down
4 changes: 2 additions & 2 deletions supplementary_style_guide/glossary_terms_conventions/general_conventions/u.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@
[discrete]
[[unix]]
==== image:images/yes.png[yes] UNIX (noun)
*Description*: UNIX is a registered trademark of The Open Group. Do not use "UNIX-like"; use an expression such as "Linux, UNIX, and similar operating systems" instead.
*Description*: UNIX is a registered trademark of The Open Group. Do not use "UNIX-like" or "UNIX-based"; use an expression such as "Linux, UNIX, and similar operating systems" or "UNIX system-based" instead.

*Use it*: yes

*Incorrect forms*: Unix, unix, UNIX-like
*Incorrect forms*: Unix, unix, UNIX-like, UNIX-based

*See also*:

Expand Down
4 changes: 2 additions & 2 deletions supplementary_style_guide/glossary_terms_conventions/general_conventions/v.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Use lowercase "v" and uppercase "CPU".
[discrete]
[[vi]]
==== image:images/yes.png[yes] vi (noun)
*Description*: "vi" is a screen-oriented text editor originally created for the Unix operating system. Do not use "VI."
*Description*: "vi" is a screen-oriented text editor originally created for the UNIX operating system. Do not use "VI."
Amrita42 marked this conversation as resolved.
Show resolved Hide resolved

*Use it*: yes

Expand All @@ -69,7 +69,7 @@ Use lowercase "v" and uppercase "CPU".
[discrete]
[[vim]]
==== image:images/yes.png[yes] Vim (noun)
*Description*: "Vim" is an acronym for Vi IMproved. In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved when ported to various Unix-based operating systems in 1992. Despite being an acronym, and despite the first word of the "About" text that is displayed when you launch the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
*Description*: "Vim" is an acronym for Vi IMproved. In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved in 1992, when ported to the UNIX system and similar operating systems. Despite being an acronym, and despite the first word of the "About" text that is displayed when you launch the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
Amrita42 marked this conversation as resolved.
Show resolved Hide resolved

*Use it*: yes

Expand Down