0_Introduction/editing_guide.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Editing Guide\n",
    "\n",
    "This is a general guide for section editors to help create a unified editing process.\n",
    "\n",
    "The editing guise is divided into two categories."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Format Editing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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:\n",
    "    \n",
    "```\n",
    "<span style=\"background-color:cyan\">GSF:LF:this is the comment text</span>\n",
    "```\n",
    "\n",
    "renders as:\n",
    "\n",
    "<span style=\"background-color:cyan\">GSF:LF: this is the comment text</span>\n",
    "\n",
    "We use cyan for format editing comments.\n",
    "\n",
    "In the chapter introduction place the following list to indicate which of the formatting \n",
    "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 \n",
    "a conclusion section. So there ought to be very few cyan editor commments. \n",
    "\n",
    "#### Format status:\n",
    "\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : LF: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : NC: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : RF: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : HF: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : GM: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : CC: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : CL: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : ST: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : FN: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : TC: Date\n",
    "* <span style=\"background-color:red\">&nbsp;&nbsp;&nbsp;&nbsp;</span> : XX: Date\n",
    "\n",
    "The following formatting errors are to be checked for. The formatting guide for the book is discussed in more detail in the [outline &#10142;](0_introduction.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Links functioning (LF)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check that all the links are functioning. Check that they point to the correct destination.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Numbering and naming convention (NC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check that the sections, figures, equations etc... are in the correct numerical order. Including table of contents. Also check numbering convention. \n",
    "* Sections: For Chapter 3: 3.1, 3.1.1, ..., 3.2, etc...\n",
    "* Figures, Tables etc...: For each main section you order the figures per section. In other words the first three figures in Section 3.1 would be Figure 3.1.1, Figure 3.1.3, Figure 3.1.2. We do not abbreviate Figure, Table, Equation etc... in the caption.\n",
    "* Number all sections, figures and tables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Referencing (RF)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We reference internal, external sections, figures, tables as follow:\n",
    "\n",
    "* `[Fig. xxx &#10142;](#destination)`: [Fig. 3.1.1 &#10142;](../3_Positional_Astronomy/3_1_Equatorial_Coordinates.ipynb#pos:fig:geo). Note we used the external symbol here &#10142; as we are pointing to another notebook. If we were pointing within the current notebook we would use &#10549;, i.e. `&#10549;`. \n",
    "* We use the abbreviated version of Figure when we reference (Fig. xx). We do not when we are refferring to a Chapter or Table.\n",
    "* `[$\\S$ xxx &#10142;](#destination)`: [$\\S$ 3.1. &#10142;](../3_Positional_Astronomy/3_1_Equatorial_Coordinates.ipynb). To refer to sections we use the $\\S$ (`$\\S$`) symbol.\n",
    "* All links within chapters using &#10142; or &#10549; must point to a numbered Figure, Section etc... \n",
    "* `[<cite data-cite='Duffett2011'>Practical Astronomy with your calculator or spreadsheet </cite> &#10548;](https://books.google.co.za/books?id=MTGYxQyW998C&dq=astronomy+with+your+calculator+or+spreadsheet)` : [<cite data-cite='Duffett2011'>Practical Astronomy with your calculator or spreadsheet </cite> &#10548;](https://books.google.co.za/books?id=MTGYxQyW998C&dq=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. \n",
    "* An equation is only numbered if it is referenced. Use same standard as Figure. Also use abbreviated Eq. when reffering to it.\n",
    "* Check that the reference label is correct, is it the same as the actual Figure etc.. caption."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Header and Footer (HF)\n",
    "\n",
    "The header and footer should look exactly like this. If someone is including some code in the standard modules cell that should be in section specific modules correct it. Are the names of links in headers and footers correct."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "\n",
    "* [Outline](0_introduction.ipynb)\n",
    "* [Glossary](1_glossary.ipynb)\n",
    "* [3. Positional Astronomy](../3_Positional_Astronomy/3_0_Introduction.ipynb)\n",
    "    * Previous: [3.1 Equatorial Coordinates (RA,DEC)](../3_Positional_Astronomy/3_1_Equatorial_Coordinates.ipynb)\n",
    "    * Next: [3.3 Horizontal Coordinates (ALT,AZ)](../3_Positional_Astronomy/3_3_Horizontal_Coordinates.ipynb) \n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import standard modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "from IPython.display import HTML \n",
    "HTML('../style/course.css') #apply general CSS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import section specific modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "from IPython.display import HTML \n",
    "HTML('../style/course.css') #apply general CSS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "\n",
    "Next: [3.3 Horizontal Coordinates (ALT,AZ)](../3_Positional_Astronomy/3_3_Horizontal_Coordinates.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Glossary and Nomenclature (GM)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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: \n",
    "\n",
    "1. Vector, scalar and matrix:\n",
    " * $a, A$ - Denotes a scalar quantity\n",
    " * $\\mathbf{A}$, $\\boldsymbol{\\mathcal{A}}$ - Denotes a matrix\n",
    " * $\\mathbf{a}$ - Denotes a vector\n",
    "\n",
    "2. $2\\times2$-Polarized vs. $N\\times N$-Unpolarized matrices: \n",
    " * $\\mathbf{A}$ - Denotes a $2\\times2$ polarized Jones matrix. Number a Jones matrix\n",
    " with any other subscript than $N$.\n",
    " * $\\boldsymbol{\\mathcal{A}}$ - Denotes a $N\\times N$ unpolarzed matrix (contain all the unpolarized quantities associated with an array in one matrix).\n",
    "\n",
    "3. Jones versus Jacobian:\n",
    " * Please use $\\mathbf{J}$ to denote a Jones matrix and $\\mathbb{J}$ to denote a\n",
    " Jacobian matrix.\n",
    "\n",
    "4. Fourier transform:\n",
    " * Please use $\\mathscr{F}\\{\\cdot\\}$ to denote the Fourier transform. \n",
    " \n",
    "5. Subscript to avoid ambiguity:\n",
    " * If one symbol is used to denote two quantities use a subscript to remove ambiguity. For instance $\\lambda$ can mean wavelength or the LM-damping factor. Add a subscript, for\n",
    "instance $\\lambda_{\\textrm{LM}}$ now refers to to the LM-damping factor, while $\\lambda$ still refers to wavelength. Please add any new subscripted symbol to the glossary.  \n",
    "\n",
    "The general list of symbols can be found in the [glossary &#10142;](1_glossary.ipynb#preface:sec:glossary)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Chapter Introduction and Conclusion (CC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chapter Introduction:\n",
    "* Provide an overview of the topics in the chapter.\n",
    "* Outline of the notebooks in the chapter.\n",
    "* Include a list of editors and contributors of the chapter.\n",
    "See [$\\S$ 5.0. &#10142;](../5_Imaging/5_0_introduction.ipynb) for exact format. Make sure editors are filled in. Add year to editor name.\n",
    "\n",
    "Chapter Conclusion:\n",
    "\n",
    "Should have following sections:\n",
    "* Summary: Summarizes chapter\n",
    "* References: All external references\n",
    "* Further reading: Material not reference but is for enrichment\n",
    "\n",
    "No good example as everyone does it different."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Correct labelling (CL)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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 &#10142;](0_introduction.ipynb)).\n",
    "\n",
    "| Chapter    |  chapterStr  |\n",
    "|------------|-------------:|\n",
    "| Preface | `preface` |\n",
    "| 1. Radio Science using Interferometers | `science` |\n",
    "| 2. Mathematical Groundwork | `math` |\n",
    "| 3. Positional Astronomy | `pos` |\n",
    "| 4. Visibility Space | `vis` |\n",
    "| 5. Imaging | `imaging` |\n",
    "| 6. Deconvolution in Imaging | `deconv` |\n",
    "| 7. Observing Systems | `instrum` |\n",
    "| 8. Calibration | `cal` |\n",
    "| 9. Putting it all together | `pract` |\n",
    "\n",
    "\n",
    "| type     |  value  |\n",
    "|----------|--------:|\n",
    "| code     | `code`  |\n",
    "| equation | `eq`    |\n",
    "| figure   | `fig`   |\n",
    "| section  | `sec`   |\n",
    "| table    | `tbl`   |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Styling (ST)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Is styling used at all if not it should. Is it used correctly. Where can it be applied."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To write a \"warning\" text box, one can use in a markdown:\n",
    "\n",
    "```\n",
    "<div class=warn>\n",
    "<b>Warning:</b> This relation assumes this particular hypothesis  \n",
    "</div>\n",
    "```\n",
    "\n",
    "To write a note \"note\" or a piece of advice, use:\n",
    "\n",
    "```\n",
    "<div class=advice>\n",
    "<b>Advice:</b> Check the homogeneity of your equations !!!\n",
    "</div>\n",
    "```\n",
    "\n",
    "To create a green summary block:\n",
    "\n",
    "\n",
    "```\n",
    "<p class=conclusion>\n",
    "  <font size=4> <b>Take-away message</b></font>\n",
    "  <br>\n",
    "  <br>\n",
    "&bull; <b>Conclusion 1</b>: Important item to remember with a specific <em>emphasized</em> word <br><br>\n",
    "&bull; <b>Conclusion 2</b>: A second important item to remember with a specific <em>emphasized</em> word.\n",
    "</p>\n",
    "```\n",
    "\n",
    "To create a \"Prerequisites\"/\"To read\" header block:\n",
    "\n",
    "```\n",
    "<p class=prerequisites>\n",
    "  <font size=4> <b>Prerequisites</b></font>\n",
    "  <br>\n",
    "  <br>\n",
    "&bull; <b>Definition of ($u$,$v$,$w$):</b> [Go to 4.1](4_1_The_Baseline.ipynb) <br><br>\n",
    "&bull; <b>The visibility function:</b> [Go to 4.3](4_3_The_Visibility_Function.ipynb)\n",
    "</p>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### File Names (FN)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Are the file names in the correct format. Example: `6_1_sky_models.ipynb`. All small letters. Name of section. Single digits if possible."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Table of Contents (TC)\n",
    "\n",
    "Check that the table of contents accurately reflects the contents of the chapter you are editing. Also check that the table of content links are working. Please create github issues for TC format errors and assign to Trienko."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Spelling (SP)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check spelling. Copy text to some spell-checker."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### General Formatting Comment (XX)\n",
    "\n",
    "If you have other formatting comments that are not summurazide above. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Content Formatting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.\n",
    "\n",
    "* What is the point of the section?\n",
    "* Is that point clear or could it be presented in a different way?\n",
    "* Are the examples useful?\n",
    "* Are there holes or assumptions in the section content which need to be improved?\n",
    "* What could be added or removed to improve the quality of the section?\n",
    "\n",
    "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:\n",
    "    \n",
    "```\n",
    "<span style=\"background-color:red\">GSF:MC:this is the comment text</span>\n",
    "```\n",
    "\n",
    "renders as:\n",
    "\n",
    "<span style=\"background-color:red\">GSF:MC: this is the comment text</span>\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Move Content (MC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Move content somewhere else. Be specific as to why and to where it should be moved. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Re-Write Content (RC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.\n",
    "You may want to postpone correcting until you finish the chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Improve Content (IC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The content is logically flawed and needs to be improved. It is not clear or simple enough for a student to grasp.\n",
    "Be specifc in your comments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add Content (AC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add content. State the reason why."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Remove Content (EC)\n",
    "\n",
    "Completely remove the content."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### General Comment (GC)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add other general comments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional Information\n",
    "\n",
    "\n",
    "### Spelling Style\n",
    "\n",
    "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](http://www.oxfordjournals.org/our_journals/mnras/for_authors/#6.2 Spelling, grammar, punctuation and mathematics) 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:\n",
    "\n",
    "> ##### Punctuation \n",
    "> 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",
    "> \n",
    "> 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). \n",
    "> \n",
    "> M-rules (three dashes in TeX/LaTeX) are not used in MNRAS.\n",
    "> \n",
    "> ##### Spelling and grammar \n",
    "> 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). \n",
    "> \n",
    "> ‘None’ is a singular word (none of the stars is a white dwarf), whilst ‘data’ is a plural word (these data show…). \n",
    "> \n",
    "> 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. \n",
    "> \n",
    "> For any other spellings, use whichever version is listed first in the Oxford English Dictionary.\n",
    "\n",
    "### Editor/Author Collaboration\n",
    "\n",
    "#### 2016\n",
    "\n",
    "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.\n",
    "\n",
    "#### 2017\n",
    "\n",
    "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 \n",
    "to work on this branch is as follow:\n",
    "\n",
    "* `git fetch upstream`.\n",
    "* `git checkout edit`.\n",
    "* `git merge upstream\\edit`.\n",
    "* Make the edits you wish to `edit` branch.\n",
    "* `git add, commit and push origin edit`.\n",
    "* Go to local fork edit branch and create a pull request to ratt-ru edit branch.\n",
    "\n",
    "Only after the authors have corrected the edits will I merge it into the main branch of ratt-ru.\n",
    "\n",
    "### Editing Attribution\n",
    "\n",
    "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."
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}