From 7c5c304ed58223045bdaf03f900dc8c00f53e6c6 Mon Sep 17 00:00:00 2001 From: Ryan Tucker Date: Mon, 12 Sep 2016 23:23:24 -0700 Subject: [PATCH] Started working on a style guide for tutorials --- docs/source/openmw-mods/differences.rst | 2 +- docs/source/openmw-mods/index.rst | 1 + docs/source/openmw-mods/mod-install.rst | 6 +++ docs/source/tutorial-style-guide.txt | 51 +++++++++++++++++++++++++ 4 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 docs/source/openmw-mods/mod-install.rst create mode 100644 docs/source/tutorial-style-guide.txt diff --git a/docs/source/openmw-mods/differences.rst b/docs/source/openmw-mods/differences.rst index be0d96c93..b112c398b 100644 --- a/docs/source/openmw-mods/differences.rst +++ b/docs/source/openmw-mods/differences.rst @@ -7,7 +7,7 @@ A brief overview of the differences between the two engines. OpenMW is designed to be able to use all the normal Morrowind mod files such as .esm/.esp plugins, texture replacers, mesh replacers, etc. .. warning:: - All external programs and libraries that depend on ''morrowind.exe'' cannot function with OpenMW. This means you should assume mods dependent on Morrowind Graphics Extender, Morrowind Code Patch, Morrowind Script Extender, etc, will *not* work correctly. + All external programs and libraries that depend on ''morrowind.exe'' cannot function with OpenMW. This means you should assume mods dependent on Morrowind Graphics Extender, Morrowind Code Patch, Morrowind Script Extender, etc, will *not* work correctly, nor will the tools themselves. Multiple Data Folders --------------------- diff --git a/docs/source/openmw-mods/index.rst b/docs/source/openmw-mods/index.rst index 755501d2f..60eae8bde 100644 --- a/docs/source/openmw-mods/index.rst +++ b/docs/source/openmw-mods/index.rst @@ -13,3 +13,4 @@ The following document is the complete reference guide to modifying, or modding, foreword differences + mod-install \ No newline at end of file diff --git a/docs/source/openmw-mods/mod-install.rst b/docs/source/openmw-mods/mod-install.rst new file mode 100644 index 000000000..682ff8b9c --- /dev/null +++ b/docs/source/openmw-mods/mod-install.rst @@ -0,0 +1,6 @@ +How To Install Mods +################### + +The following is a detailed guide on how to install mods in OpenMW using best practices. + +#. \ No newline at end of file diff --git a/docs/source/tutorial-style-guide.txt b/docs/source/tutorial-style-guide.txt new file mode 100644 index 000000000..258297642 --- /dev/null +++ b/docs/source/tutorial-style-guide.txt @@ -0,0 +1,51 @@ +#################### +Tutorial Style Guide +#################### + +Please contact Ravenwing about any questions relating to this guide. + +Foreword +-------- + +I shall try to be as brief as possible without sacrificing clarity, just as you should be when writing documentation. The SCOPE of this guide is limited to all non-source code documentation. + +References +---------- + +-Syntax: reStructuredText (ReST): http://docutils.sourceforge.net/rst.html +-Parser: Sphinx: http://www.sphinx-doc.org/en/stable/ +-British and English Spelling: https://www.spellzone.com/pages/british-american.cfm + +Language +-------- + +British English +Sorry, I'm American and I'll probably have a million relapses, but this seems to have been decided and uniformity is key! + +Text Wrapping +------------- + +DO NOT manually decide where each line ends! Enable text wrapping in your text editor! (usually under View) Even Notepad allows automatic text wrapping, so use it. If you program, you may be used to keeping your lines under 80 characters wide and manually pressing enter, but don't. This is because we are writing mostly prose. When someone has to come in and edit portions of text that puts all this out of alignment, it takes FOREVER to readjust everything. Plus, indentation is very important in ReST, and you may forget to indent properly. + +Indentations +------------ + +This isn't as important, especially since Sphinx converts tabs to spaces, but I find it much easier to keep large blocks of things aligned if you just tab. If you can edit your tab width, please set it to 4 spaces. + +Spaces +------ + +Use only one space after each sentence. Some people were taught two spaces, but this is a carry-over from typewriters. Even though your text editor is probably using monospaced characters like a typewriter, the formats Sphinx is converting into will make all the adjustments they need to be beautifully legible. + +Commas +------ + +Oxford comma. Use it. I know this goes against using British English, but this is technical writing. You cannot assume our audience will know from context if the last two items in a list are grouped or not. +I also prefer parentheticals to commas around gerund phrases. + +Files and Extensions +-------------------- + +When referring to a filename or filepath use the double single quotes as for inline literals. (e.g. ''morrowind.exe'') +When referring to a file extension by itself use all caps without the dot beforehand. (e.g. ZIP instead of .zip or .ZIP) +