When format editing a section add comments by starting with your initials, the formatting tag abbreviation and wrap the comment in a css span tag to color the text so that it sticks out, an example is:
<span style="background-color:cyan">GSF:LF:this is the comment text</span>renders as:
GSF:LF: this is the comment text
We use cyan for format editing comments.
In the chapter introduction place the following list to indicate which of the formatting errors were checked by the editors in each chapter. This is not to indicate if the author corrected the suggestions. Only to indicate whether the content was checked by an editor. If they are red they were not checked. If they are green they were. The aim is to as far as possible correct formating errors without involving the author. Except for big changes like a conclusion section. So there ought to be very few cyan editor commments.
The following formatting errors are to be checked for. The formatting guide for the book is discussed in more detail in the outline ➞.
Check that all the links are functioning. Check that they point to the correct destination.
Check that the sections, figures, equations etc... are in the correct numerical order. Including table of contents. Also check numbering convention.
We reference internal, external sections, figures, tables as follow:
[Fig. xxx ➞](#destination): Fig. 3.1.1 ➞. Note we used the external symbol here ➞ as we are pointing to another notebook. If we were pointing within the current notebook we would use ⤵, i.e. ⤵. [$\S$ xxx ➞](#destination): $\S$ 3.1. ➞. To refer to sections we use the $\S$ ($\S$) symbol.[<cite data-cite='Duffett2011'>Practical Astronomy with your calculator or spreadsheet </cite> ⤴](https://books.google.co.za/books?id=MTGYxQyW998C&dq=astronomy+with+your+calculator+or+spreadsheet) : Practical Astronomy with your calculator or spreadsheet ⤴. Make sure that citations are as follows and that the text that is displayed is the name of book article. Make sure reference is in chapters .bib file. Import standard modules:
In [3]:
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline
from IPython.display import HTML
HTML('../style/course.css') #apply general CSS
Out[3]:
Import section specific modules:
In [4]:
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline
from IPython.display import HTML
HTML('../style/course.css') #apply general CSS
Out[4]:
Are all the new definition in italics when first used in a chapter and described in the glossary. Are the mathematical symbols in nomenclature. Is the basic mathematic style guide followed:
Vector, scalar and matrix:
$2\times2$-Polarized vs. $N\times N$-Unpolarized matrices:
Jones versus Jacobian:
Fourier transform:
Subscript to avoid ambiguity:
The general list of symbols can be found in the glossary ➞.
Chapter Introduction:
Chapter Conclusion:
Should have following sections:
No good example as everyone does it different.
Make sure that all figure, section, equation and citation strings contain the correct label string format, i.e. chapterStr:type:uniqueID. Do they use the correct label string (see outline ➞).
| Chapter | chapterStr |
|---|---|
| Preface | preface |
| 1. Radio Science using Interferometers | science |
| 2. Mathematical Groundwork | math |
| 3. Positional Astronomy | pos |
| 4. Visibility Space | vis |
| 5. Imaging | imaging |
| 6. Deconvolution in Imaging | deconv |
| 7. Observing Systems | instrum |
| 8. Calibration | cal |
| 9. Putting it all together | pract |
| type | value |
|---|---|
| code | code |
| equation | eq |
| figure | fig |
| section | sec |
| table | tbl |
Is styling used at all if not it should. Is it used correctly. Where can it be applied.
To write a "warning" text box, one can use in a markdown:
<div class=warn>
<b>Warning:</b> This relation assumes this particular hypothesis
</div>To write a note "note" or a piece of advice, use:
<div class=advice>
<b>Advice:</b> Check the homogeneity of your equations !!!
</div>To create a green summary block:
<p class=conclusion>
<font size=4> <b>Take-away message</b></font>
<br>
<br>
• <b>Conclusion 1</b>: Important item to remember with a specific <em>emphasized</em> word <br><br>
• <b>Conclusion 2</b>: A second important item to remember with a specific <em>emphasized</em> word.
</p>To create a "Prerequisites"/"To read" header block:
<p class=prerequisites>
<font size=4> <b>Prerequisites</b></font>
<br>
<br>
• <b>Definition of ($u$,$v$,$w$):</b> [Go to 4.1](4_1_The_Baseline.ipynb) <br><br>
• <b>The visibility function:</b> [Go to 4.3](4_3_The_Visibility_Function.ipynb)
</p>Are the file names in the correct format. Example: 6_1_sky_models.ipynb. All small letters. Name of section. Single digits if possible.
Check spelling. Copy text to some spell-checker.
The main goal of the editors is to consider the quality of the content, each editor should consider these questions and hopefully answer them by the end of editing a section.
When content editing a section add comments by starting with your initials, the formatting tag abbreviation and wrap the comment in a css span tag to color the text so that it sticks out, an example is:
<span style="background-color:red">GSF:MC:this is the comment text</span>renders as:
GSF:MC: this is the comment text
We use red and yellow for content comments. Red means that the comment should definitely be implemented by the original author. Yellow means that the comment should be seen as a suggestion only. The different content tags are listed below. Please make github issues for the different editor comments.
Move content somewhere else. Be specific as to why and to where it should be moved.
Content needs to be rewritten as it is written in incorrect language. Or the sentences are not clear. These are the comments that the editors may be able to adress themselves. You may want to postpone correcting until you finish the chapter.
The content is logically flawed and needs to be improved. It is not clear or simple enough for a student to grasp. Be specifc in your comments.
Add content. State the reason why.
Add other general comments.
Since we all come from different backgrounds on our spelling stylea we need to formalize the text on one style, we will use the MNRAS style which is essentially British English spelling, e.g. colour instead of color, but uses 'z' in most '-ize' ending words. The specific direction taken from the MNRAS style guide:
Punctuation
Hyphens (one dash in LaTeX) should be used for compound adjectives (e.g. low-density gas, least-squares fit, two-component model). This also applies to simple adjectival units (e.g. 1.5-m telescope, 284.5-nm line), but not to complex units or ranges, which could become cumbersome (e.g. 15 km s–1 feature, 100–200 µm observations). Some words (e.g. time-scale) are always hyphenated as part of journal style (see below).
N-rules (two dashes in LaTeX): these are longer than hyphens and are used (i) to separate key words, (ii) as parentheses (e.g. the results – assuming no temperature gradient – are indicative of …), (iii) to denote a range (e.g. 1.6–2.2 µm), and (iv) to denote the joining of two words (e.g. Kolmogorov–Smirnov test, Herbig–Haro object).
M-rules (three dashes in TeX/LaTeX) are not used in MNRAS.
Spelling and grammar
Please use British English spellings – e.g. centre not center, labelled not labeled. For words ending in -ise/yse or -ize follow this style: use -ise/yse for devise, surprise, comprise, revise, exercise, analyse; use -ize for recognize, criticize, minimize, emphasize, organize, ionize, polarize, parametrize (note the spelling of this word in particular).
‘None’ is a singular word (none of the stars is a white dwarf), whilst ‘data’ is a plural word (these data show…).
Miscellaneous journal spellings: acknowledgements, artefact, best-fitting (not best-fit), disc (except computer disk), haloes (not halos), hotspot, none the less, non-linear, on to, time-scale.
For any other spellings, use whichever version is listed first in the Oxford English Dictionary.
We leave it to the editors and authors on how best to collaborate on incorporating edits and comments into the text. A suggestion is for the editor to send a pull request to the author's github fork. Once the edits are worked out, the author will then do a pull request to the main github repository.
We will be using an edit branch to keep a stable version which can be released to the students. I have created a branch called edit in the ratt-ru repository. So the steps to work on this branch is as follow:
git fetch upstream.git checkout edit.git merge upstream\edit.edit branch.git add, commit and push origin edit.Only after the authors have corrected the edits will I merge it into the main branch of ratt-ru.
At the introduction of each chapter there is a list of chapter writers and editors. Please add your name to the editor's list, include the particular section number which you edited. We need this so we can keep track of who knows about each section. And, we want to give you recognition for your work.
In [ ]: