<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">Hi<div class=""><br class=""><blockquote type="cite" class="">On 24 Dec 2015, at 15:55, Richard Duivenvoorde <<a href="mailto:richard@duif.net" class="">richard@duif.net</a>> wrote:<br class=""><br class="">Hi PSC/Community,<br class=""><br class="">Because I think we should attract more people to write documentation for<br class="">QGIS, I thought we should make it easier to fix/write docs.<br class=""><br class="">My idea: let's keep our rst framework, but do the editing/viewing in<br class="">Github..<br class=""><br class="">First: look at the following two examples:<br class=""><br class="">[0]<br class=""><a href="https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md" class="">https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md</a><br class=""><br class="">and<br class=""><br class="">[1]<br class="">https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst<br class=""><br class="">As you can see the first one is immediately readable (and more editable)<br class="">in Github.<br class="">We have (I think from our Latex roots) a lot of extra styling<br class="">directives/stuff in our docs. It looks like this now:<br class=""><br class="">[3]<br class="">http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html#the-vector-properties-dialog<br class=""><br class="">I propose and tested the following:<br class=""><br class="">- move images from resources into an images directory in the source<br class="">folder, see<br class="">[4]<br class="">https://github.com/qgis/QGIS-Documentation/tree/master_github_e/source/docs/user_manual/working_with_vector<br class=""><br class="">- remove all the :guilabel: :menuselection: and other directives to make<br class="">it easier to edit/view in Github<br class=""><br class="">- get rid of all/most of the image/icon shortcuts (needed for inline<br class="">images) from source.conf and put them in the source file where they are used<br class=""><br class="">- remove substitutions like |qg| (for QGIS) and |nix| (for linux icon).<br class="">It clutters the source as seen on Github.<br class=""></blockquote><div class=""><br class=""></div><div class="">Just bouncing the idea around: If we follow all this logic surely it is better to switch to Markdown which is a lot more mainstream and simple to pick up and use because of its cleaner syntax? I guess with Markdown we lose the advantage of RST that we do have: richer syntax cross referencing, multi-chapter support, translation support etc. ? Which of these are we still planning to keep?</div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">Regards</div><div class=""><br class=""></div><div class="">Tim</div><div class=""><br class=""></div><br class=""><blockquote type="cite" class=""><br class="">I branched docs and changed one file, look at the Github preview now:<br class=""><br class="">[6]<br class=""><a href="https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst" class="">https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst</a><br class=""><br class="">As you can see it is the same file as the rst above [1], but here you do<br class="">not see all the :xxxx: directives, you see the images etc. Hopefully<br class="">much easier to add or fix a paragraph here.<br class=""><br class="">I did not yet move all the image substitutions but if you put those IN<br class="">the source file and point to the local image dir, you see them also in<br class="">Github.<br class=""><br class="">An example local build here next to a classic build:<br class="">http://i.imgur.com/SjSC94N.png<br class=""><br class="">I also build the pdf. Because style directives like :guilabel: also are<br class="">followed by text in `back quotes` it still gets a special styling:<br class="">italic in pdf and 'cite' in html<br class="">So the stuff that is now bleu in html can for example be made italic or<br class="">bold easily.<br class=""><br class="">So should I make a QEP for this.<br class="">Should I just GO?<br class="">Do people REALLY miss the extra styling?<br class=""><br class="">Otto what do you think?<br class=""><br class="">The whole plan/vision is that by looking cleaner/better in Github, it is<br class="">easier for people to edit/fix stuff in docs: so we have better<br class="">Documentation!<br class=""><br class="">Parts of it can be automated, as nobody has recent translated images<br class="">there is not so much work in resources directory.<br class="">I think we should start with the User Manual first.<br class="">Then Python Cookbook, then Training Manual..<br class=""><br class="">Regards,<br class=""><br class="">Richard Duivenvoorde<br class=""><br class="">PS, part 2 of all this is to fix some styling in the sphinx templates:<br class="">remove bootstrap so hopefully it is easier to use docs in Webkit-widgets<br class="">again (an early attempt in processing failed, I think because bootstrap<br class="">uses to much javascript magic to make content responsive)..<br class=""><br class=""><br class="">_______________________________________________<br class="">Qgis-psc mailing list<br class="">Qgis-psc@lists.osgeo.org<br class="">http://lists.osgeo.org/mailman/listinfo/qgis-psc<br class=""></blockquote><br class=""><div class=""><span>—</span><br class=""><span><br class=""></span><span style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><br class="Apple-interchange-newline"><span><img height="66" width="160" apple-inline="yes" id="BE44AC3E-A101-4849-BCDA-5B2484B1D7F2" apple-width="yes" apple-height="yes" src="cid:62C890D4-3964-4609-BDE6-7536D5FBDD70" class=""></span><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-align: center;" class=""><br class="Apple-interchange-newline"><br class=""></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-align: center;" class="">Tim Sutton</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-align: center;" class=""><br class=""></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><div style="text-align: center;" class="">Visit <a href="http://kartoza.com" class="">http://kartoza.com</a> to find out about open source:</div><div style="text-align: center;" class=""><br class=""></div><div class=""><div style="text-align: center;" class="">* Desktop GIS programming services</div><div style="text-align: center;" class="">* Geospatial web development</div><div style="text-align: center;" class="">* GIS Training</div><div style="text-align: center;" class="">* Consulting Services</div><div style="text-align: center;" class=""><br class=""></div><div class=""><div style="text-align: center;" class="">Skype: timlinux Irc: timlinux on #qgis at <a href="http://freenode.net" class="">freenode.net</a></div><div style="text-align: center;" class="">Tim is a member of the QGIS Project Steering Committee</div><div style="text-align: center;" class=""><br class=""></div><div style="text-align: center;" class="">Kartoza is a merger between Linfiniti and Afrispatial</div></div></div></div>
</span></div><br class=""></div></body></html>