search

Society-of-Flight-Test-Engineers / handbook-2013

A port of the 2013 SFTE Reference Handbook to bookdown
7 stars 9 forks source link

Please proofread update to Math Mode Style Guide #199

Open cooknl opened 4 years ago

cooknl commented 4 years ago

https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/wiki/Handbook-Markdown-Style-Guide#math-mode

I'm attempting to clarify when to use inline math mode and when not.

cooknl commented 4 years ago

The formatting of "values" in various contexts has me scratching my head.

Plain text 299792458 299792458

Plain text scientific notation 2.99792458 x 10^8^ 2.99792458 x 108

Inline math mode \(299792458\) 299792458

Inline math mode scientific notation \(2.99792458 \times 10^8\) 2.99792458 \times 10^8

flighttestfact commented 4 years ago

"Use \text{ } for units, commas, embedded qualifiers (e.g. \text{, where })" I think this only applies in display mode, not for inline mode. For inline mode, you can just exit math inline mode and type normal text.

flighttestfact commented 4 years ago

The formatting of "values" in various contexts has me scratching my head.

Plain text 299792458 299792458

Plain text scientific notation 2.99792458 x 10^8^ 2.99792458 x 108

Inline math mode \(299792458\) 299792458

Inline math mode scientific notation \(2.99792458 \times 10^8\) 2.99792458 \times 10^8

I like the look of math mode over plain text, but that's an aesthetic opinion.

flighttestfact commented 4 years ago

https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/wiki/Handbook-Markdown-Style-Guide#math-mode

I'm attempting to clarify when to use inline math mode and when not.

I think the link is broken.

cooknl commented 4 years ago

Concur with both the aesthetic choice and the inline "mode toggle" statements above.

@rwstanfo

On Sat, Mar 14, 2020, 18:21 flighttestfact notifications@github.com wrote:

https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/wiki/Handbook-Markdown-Style-Guide#math-mode http://url

I'm attempting to clarify when to use inline math mode and when not.

I think the link is broken.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/issues/199#issuecomment-599146856, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABHBHY73YSWKVPE25NO357DRHQGOLANCNFSM4LJJOS5Q .

cooknl commented 4 years ago

Link fixed

cooknl commented 4 years ago

Actually, there are times when toggling doesn't work, for example: \(\psi = \atan \left( X\), \(Y \right) \) doesn't render because the \left( is unmatched inside of the inline delimiters.

markjonesjr commented 4 years ago

You can use commas inside math mode.

On Sat, Mar 14, 2020, 8:26 PM CAPN notifications@github.com wrote:

Actually, there are times when toggling doesn't work, for example: (\psi = \atan \left( X), (Y \right) ) doesn't render because the \left( is unmatched inside of the inline delimiters.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/issues/199#issuecomment-599155509, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABYB2DFHCA27G3D7NMOPE6DRHQVGBANCNFSM4LJJOS5Q .

cooknl commented 4 years ago

Valid, but the spacing is jacked

On Sat, Mar 14, 2020, 20:37 Mark Jones Jr. notifications@github.com wrote:

You can use commas inside math mode.

On Sat, Mar 14, 2020, 8:26 PM CAPN notifications@github.com wrote:

Actually, there are times when toggling doesn't work, for example: (\psi = \atan \left( X), (Y \right) ) doesn't render because the \left( is unmatched inside of the inline delimiters.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub < https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/issues/199#issuecomment-599155509 , or unsubscribe < https://github.com/notifications/unsubscribe-auth/ABYB2DFHCA27G3D7NMOPE6DRHQVGBANCNFSM4LJJOS5Q

.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/Society-of-Flight-Test-Engineers/handbook-2013/issues/199#issuecomment-599156139, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABHBHY2CVIITMJH2OIFFTCLRHQWNNANCNFSM4LJJOS5Q .

rwstanfo commented 4 years ago

I concur with using math mode for values in the text. I've reviewed the math mode style guide and have no issues with it. I will need to circle back and apply some of the guidance to sections I've worked on however.

If you can spare the time to go back, that would be helpful.

Also, we are learning as we go, adding items to the style guide, and I expect to be going back at the end to do a final style scrub.

rwstanfo commented 4 years ago

One comment on... comments. The block syntax is a bit cumbersome for small comments. I've been using the following syntax, which is only marginally better.

“<!--- comment here --->”

Haven't found a better way yet for dropping quick comments. Any thoughts?

cooknl commented 4 years ago

I concur that they are a tad on the cumbersome side.

Intent is to avoid embedding HTML in the markdown, if at all possible.

It's not a major foul at this point, and it's not something I'm going to fall in my sword over.

flighttestfact commented 4 years ago

One comment on... comments. The block syntax is a bit cumbersome for small comments. I've been using the following syntax, which is only marginally better.

Haven't found a better way yet for dropping quick comments. Any thoughts?

I'm not seeing an alternate syntax for comments...am I missing something?

rwstanfo commented 4 years ago

Now you should be able to the comment syntax in my above post. GitHub interpreted it as an actual comment when I didn’t use surrounding quotation marks

...because GitHub uses "GitHub-flavored" Markdown in all its text fields!

rwstanfo commented 4 years ago

@cooknl can you be more specific for the desired “degree” sign and how to generate it? Are you using an html tag to render it or some other method? When I look through the source code for the style guide page it still just appears as a rendered degree sign.

cooknl commented 4 years ago

The style guide recommends a triple back tick "block" comment. Ryan had been using an HTML style comment (which was ironically hidden until he put it in quotes).

cooknl commented 4 years ago

Regarding the degree symbol, it's a Unicode symbol that I copied and pasted directly from search results in a browser to my text editor. I haven't looked closely at how to use alternative representations for it to render.

Almost all modern text editors support UTF-8 encodings directly.

cooknl commented 4 years ago

Okay, to summarize:

  1. [ ] We'll use inline math mode for numeric values (similar to using inline math mode for symbols
  2. [ ] We'll use \text{ } for embedded "regular words", noting that in some inline cases, the math mode can be "toggled" before and after text.
  3. [ ] I'll generalize and say any UTF-8 character should be used directly, not poorly approximated with ASCII characters (degree symbols and subscript zeros for "naughts" instead of lowercase "o" in either case, for example)
  4. [ ] Both commenting styles are acceptable, knowing that generally "raw" HTML is to be avoided in markdown.

Closing arguments? Unmentioned concerns?