Updates for 3.0 #2258

anitagraser · 2017-12-10T16:35:08Z

as well as some fixes for consistency reasons and some details that have been missing so far.

Needs a new screenshot for "Creating a new Shapefile layer dialog" that shows the "Geometries with Z coordinate" checkbox.
Fix #1937
ref #2252 (miss a screenshot)

as well as some fixes for consistency reasons and some details that have been missing so far. Needs a new screenshot for "Creating a new Shapefile layer dialog" that shows the "Geometries with Z coordinate" checkbox.

yjacolin

Just one typo to change. Thanks Anita!

yjacolin · 2017-12-11T08:53:41Z

source/docs/user_manual/managing_data_source/create_layers.rst

-Empty, editable memory layers can be defined using :menuselection:`Layer -->
-Create Layer --> New Temporary Scratch Layer`. Here you can even create
+Empty, editable temporary scratch layers can be defined using :menuselection:`Layer -->
+Create Layer --> New Temporary Scratch Layer`. Here you can  create


Here you can create Too much space before create

yjacolin · 2017-12-11T08:54:32Z

source/docs/user_manual/managing_data_source/create_layers.rst

@@ -319,8 +319,8 @@ The :guilabel:`DXF Export` dialog allows the user to:

 .. _paste_into_layer:

-Create layer from a clipboard
-=============================
+Createing new layers from the clipboard


Creat*e*ing -> Creating

DelazJ

Thanks @anitagraser This is why we need more reviewers particularly when big parts of doc are restructured. It really looks better and consistent.
I would be interested in backporting this commit to 2.18 (because text looks better but also for URL consistency) and, except Z dimension, there's no incompatibility yet . Any objection?

DelazJ · 2017-12-10T18:07:22Z

source/docs/user_manual/managing_data_source/create_layers.rst

+|selectString| and :guilabel:`Date` |selectString| attributes are
+supported. Additionally, depending on the attribute type, you can also define
+the length and precision of the new attribute column. Once you are happy with the
+attributes, click **[OK]** and provide a name for the Shapefile. QGIS will


This has changed: in the new dialog the user fills the shapefile's name at the beginning, not after he clicks ok.

Yes, I see the changes in master now.

I've updated the instructions.

DelazJ · 2017-12-10T18:12:46Z

source/docs/user_manual/managing_data_source/create_layers.rst

-saved and will be discarded when QGIS is closed. See also :ref:`paste_into_layer`.
+|radioButtonOff|:guilabel:`Polygon` layers. Temporary Scratch Layers only exist in
+memory. This means that they are not saved and will be discarded when QGIS is closed. 
+See also :ref:`paste_into_layer`.


I wonder if what temporary scratch layer is (and how it lives or dies) shouldn't be exposed before steps to create it… ie move these last sentences to the beginning

DelazJ · 2017-12-10T18:13:08Z

source/docs/user_manual/managing_data_source/create_layers.rst

 |radioButtonOff|:guilabel:`Multipoint`, |radioButtonOff|:guilabel:`Multiline`
 and |radioButtonOff|:guilabel:`Multipolygon` Layers beneath
 |radioButtonOn|:guilabel:`Point`, |radioButtonOff|:guilabel:`Line` and
-|radioButtonOff|:guilabel:`Polygon` Layers. Temporary Scratch Layers are not


The comment actually concerns the not changed lines above: the spelling of geometry type has changed in recent commits, eg MultiPolygon instead of Multipolygon.

Forgot to say that it's no longer radio buttons but all in a combobox

DelazJ · 2017-12-10T18:21:02Z

source/docs/user_manual/managing_data_source/create_layers.rst

-Joins and complex queries can also be created simply by directly using the
-names of the layers that are to be joined.
+Joins and complex queries can also be created, for example, to join airports
+and county information:


county or country? (see the sample code)

Ah, should be country, but doesn't really matter.

anitagraser · 2017-12-11T09:28:53Z

@DelazJ Thanks and sure feel free to backport any part that's appropriate for 2.18.

anitagraser · 2017-12-16T14:59:46Z

As far as I can see, all requested changes have now been addressed. Thank you for reviewing!

DelazJ

Some more comments

DelazJ · 2017-12-17T07:30:48Z

source/docs/user_manual/managing_data_source/create_layers.rst



 .. index:: Save layer
 .. _general_saveas:

-Save layer from an existing file
-================================
+Creating new layers from an existing layers


An existing layer

DelazJ · 2017-12-17T10:15:16Z

source/docs/user_manual/managing_data_source/create_layers.rst

@@ -163,35 +163,38 @@ predefined structure.
 Creating a new Temporary Scratch Layer
 --------------------------------------

-Empty, editable memory layers can be defined using :menuselection:`Layer -->
-Create Layer --> New Temporary Scratch Layer`. Here you can even create
+Temporary Scratch Layers only exist in memory. This means that they are not saved 


@anitagraser could you please review #2260? I included some changes in this section that i forgot to propose here. It'd be nice to harmonize this description to avoid double work for translation team.

I've integrated your changes here.

DelazJ · 2017-12-17T10:28:48Z

source/docs/user_manual/managing_data_source/create_layers.rst

+The first step is to provide a path and name for the Shapefile. QGIS will
+automatically add the :file:`.shp` extension to the name you specify
+Next, choose the type of layer (point, line or polygon) and optional Z or M 
+dimensions, as well as the CRS (coordinate reference system).


Should it be Coordinate Reference System (ie titled)?

Do you usually write it in title case? It's not a name, so I'd usually keep it in lower case.

Good question! Never paid attention to it. I can see both spelling but i think you are not wrong writing it in lower case

DelazJ · 2017-12-17T10:35:31Z

First of all, let me stress again that i approve changes in this PR and agree that they add consistency, hence improvements. This is the way we need to go.
BUT
I'd also like to raise some issues it will create once merged. I've already expressed this concern many times ago (eg qgis/QGIS#4023 (comment) or in this compilation ) but will do it again, for the last time: because QGIS HELP system is based on full url, merging this pull request will break links from the dxf export, save vector/raster as, embedded layers dialogs (and so will do some of the other PRs Anita opened - Thanks and keep on fixing those headings and formulation, please). In the past, i silently fixed the url in QGIS repo when the changes in docs occured by my fault but I'm not sure that:

QGIS Help system should rely on the memory of a single person to not bring readers to a wrong place;
QGIS Doc team should have to chase wrong links in the application
QGIS Doc team should worry about breaking url in the application, hence avoid changes that would improve the user manual (in this pr, headings are simply renamed so user will fallback to the chapter level but in some cases we can need to move sections to another chapter - see eg Refactoring the Supported data formats chapter #1996 for the silent fix i mentioned beforehand - and with QGIS 3 changes, this could likely occur again when features are documented).

So, what to do? I can see two options (there might be others):

use rst internal anchors (the one we use to cross-link sections) which likely do not have any reason to change. I don't know how easy the implementation could be nor whether it's desirable or not to build help infrastructure close to rst language but this guarantee that help urls are always uptodate, regardless the heading and the chapter.
report missing links in application so that devs fix them. @jgrocha wrote a script to list unreached links (see it in action here); it could be improved if needed, and show warning (or whatever better suits) when a link is not found. Anybody willing to fix it can then do that.

Voilà my last call on what looks like an issue to me but i could be wrong. A lot has already been done; it'd be a pity to lose those missing bits. And sorry for the length (i wanted it as documented as possible - aren't we in Docs repo?).
Cc @m-kuhn @alexbruy @rduivenvoorde @SrNetoChan @ghtmtt ...

anitagraser · 2017-12-17T12:11:11Z

Thank you for the explanations @DelazJ! I wasn't aware that the QGIS help system relies on headings rather than anchors. Sound to me like anchors are the way to go.

5725f90

DelazJ · 2017-12-18T07:47:25Z

@rduivenvoorde anything wrong with the build? The latest commit shouldn't have failed.

rduivenvoorde · 2017-12-18T09:47:15Z

@DelazJ all is ok now isn't it? Travis had troubles receiving Python apparently (nothing to do with the commits). But next build was ok.

ghtmtt · 2017-12-19T14:17:51Z

@DelazJ IMHO rst anchors are the way to follow. Also in the Processing Help files refactoring all the algorithms have an unique anchor (that will remain unique also in the future).
I think @alexbruy knows the code perfectly. What is your opinion?

rduivenvoorde · 2017-12-19T15:16:19Z

@m-kuhn @alexbruy @rduivenvoorde @SrNetoChan @ghtmtt @wonder-sk

About the searching for any doc url's in the QGIS source files:

Martin was proposing a long time ago that we should have an (ini?) file containing 'key' to 'url's.
So in the source there will be a reference ONLY to the key.
There has to be some 'find_url_for_key' method then off course too...

This indirection would make it easier to:

check if urls are stil valid/reachable
grep sources to see if all keys are still used

Is this something to consider?

m-kuhn · 2017-12-19T15:33:44Z

@rduivenvoorde Could we also grep the sources for QgsHelp::openHelp and do the check on that? I think that should have the same result and there won't be the requirement to maintain a separate file additionally.

DelazJ · 2017-12-19T15:54:09Z

Could we also grep the sources for QgsHelp::openHelp and do the check on that?

@m-kuhn isn't it what is done in the aforementioned script from @jgrocha ? (unless I misunderstand)

m-kuhn · 2017-12-19T16:01:22Z

Oh, yes, pretty much :)

rduivenvoorde · 2017-12-19T17:24:35Z

@m-kuhn yep, except that the ini file could be maintained and controlled by documentation team:
moving pages around in the doc tree, adding another 'anchor'...
Keys and Url would be in one place instead of scattered over the sources.
I was hoping that in this file would 'merge' other help systems we have...
Grepping is not for a normal task for average Windows user...

m-kuhn · 2017-12-19T18:28:40Z

I see. Why not doing that on the server? Less deploy problems. And easy to do with mod rewrite etc.

rduivenvoorde · 2017-12-20T08:16:23Z

@m-kuhn It is not easy to do. I'll show you our current server configs if you want. Please do not force more rewrites, redirects, etc etc etc etc
But happy to hand over that responsibility over these though, if it is so 'easy'!

Else forget the idea. If at least we check the url's in feature freeze so for every release they are all valid.

m-kuhn · 2017-12-20T08:21:59Z

Sorry for claiming that it's easy, I admit I don't know about the server setup and I'm sure that everything behind is not a simple task. You are doing a great job with maintaining this.
I would still appreciate if we could discuss a mapping on the server. From what I can see this will be more flexible and maintainable than one on clients. If it is shipped with the binaries, each change (and changes are expected or we wouldn't put this system in place at all) needs to go through an update, and unfortunately not everyone is always on the latest point release.

as new first class citizen

anitagraser · 2018-01-02T14:08:42Z

From a documentation writer's perspective, it would feel more empowering if changes in the documentation structure could be made without bothering with the actual software sources.
Also strong +1 for Richard's "Grepping is not for a normal task for average Windows user...". If we want to involve more people in writing documentation, most of the tasks should be possible by using Github's web interface and checking Travis messages.

SrNetoChan · 2018-01-02T18:19:53Z

About getting more people writing documentation, I have been preparing a PR to make the figures show in github rst preview.

#2301

I am hoping to have some discussion around the inline substituitions, please comment if you have any concerns or ideas.

Anyway, about the "Grepping", we need to remember that not everything can be done on github. There is no conflicts management, it's not possible to upload/edit new files. So we will always need to "grepping" guys that can manage that for others writers. I am ok with it.

SrNetoChan · 2018-01-02T23:31:31Z

Regarding the helping system, even using the sphinx anchors I would like to explore the idea of the {key : value} ini file as a one place to maintain.

One of the problems that we may have is not having certain sections of the documentation ready by the time of QGIS release, therefore, we won't know what link anchor to use in the application side. @alexbruy could the QGIS aplication rely on this key value file (editable on the documentation side) to redirect the user to the right section? This way we could update that file when needed.

m-kuhn · 2018-01-03T08:20:06Z

From a documentation writer's perspective, it would feel more empowering if changes in the documentation structure could be made without bothering with the actual software sources. Also strong +1 for Richard's "Grepping is not for a normal task for average Windows user...". If we want to involve more people in writing documentation, most of the tasks should be possible by using Github's web interface and checking Travis messages.

I totally agree that doc writers should not bother with the app sources nor have to use grep or other command line tools anywhere.
I can assure you that the system I have in mind does not require any of these tasks.

m-kuhn · 2018-01-03T09:53:04Z

Following up on this, none of the approaches outlined in here would require such a manual step.

In general I think the following system should allow for minimal manual effort while having a good overview of the status:

write the doc
create a link in the source code
have a system that regularly (e.g. nightly) checks if the links in the code point to real targets (something like the aforementioned script from @jgrocha)
this script updates a table in the web with 3 states
- documentation ok
- documentation missing (not yet done)
- documentation did exist but no longer does exist (redirect required)

DelazJ · 2018-01-16T12:03:33Z

@m-kuhn @rduivenvoorde thanks for this brainstorming. What/when would then be the next step?

Fix #2252

DelazJ · 2018-02-17T05:10:30Z

Let's move ahead and clean pr queue

DelazJ · 2018-02-17T05:11:41Z

Thanks Anita

Updates for 3.0

f80ce61

as well as some fixes for consistency reasons and some details that have been missing so far. Needs a new screenshot for "Creating a new Shapefile layer dialog" that shows the "Geometries with Z coordinate" checkbox.

yjacolin requested changes Dec 11, 2017

View reviewed changes

DelazJ reviewed Dec 11, 2017

View reviewed changes

anitagraser added 2 commits December 11, 2017 10:19

Fixed typos based on review

5bb07e1

Fixed typo

68f162a

DelazJ mentioned this pull request Dec 11, 2017

Some clarification and consistency in Create layers chapter #2260

Merged

anitagraser added 2 commits December 16, 2017 14:44

Moved instructions to provide Shapefile name

4715d2c

Explain temporary scratch layers first

d6ef3d2

DelazJ reviewed Dec 17, 2017

View reviewed changes

Fixed typo

92dfc78

anitagraser and others added 2 commits December 17, 2017 14:09

Integrated changes suggested for 2.18 docs

7eb1715

5725f90

Remove duplicated reference

0967230

DelazJ approved these changes Dec 18, 2017

View reviewed changes

Move "Add new GeoPackage layer" section to the top

8d938f3

as new first class citizen

Add New shapefile screenshot

02f53c1

Fix #2252

DelazJ merged commit 47c7feb into master Feb 17, 2018

DelazJ deleted the anitagraser-patch-1 branch February 17, 2018 05:11

DelazJ mentioned this pull request Feb 18, 2019

Fix link to drag and drop designer help qgis/QGIS#9195

Merged

agiudiceandrea mentioned this pull request Feb 23, 2021

Fix "Save Vector/Raster Layer as..." dialog window Help button link to User Manual qgis/QGIS#41746

Merged

Updates for 3.0 #2258

Updates for 3.0 #2258

Conversation

anitagraser commented Dec 10, 2017 • edited by DelazJ Loading

yjacolin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DelazJ left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anitagraser commented Dec 11, 2017

anitagraser commented Dec 16, 2017

DelazJ left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anitagraser Dec 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DelazJ commented Dec 17, 2017

anitagraser commented Dec 17, 2017

DelazJ commented Dec 18, 2017

rduivenvoorde commented Dec 18, 2017

ghtmtt commented Dec 19, 2017

rduivenvoorde commented Dec 19, 2017

m-kuhn commented Dec 19, 2017

DelazJ commented Dec 19, 2017

m-kuhn commented Dec 19, 2017

rduivenvoorde commented Dec 19, 2017

m-kuhn commented Dec 19, 2017

rduivenvoorde commented Dec 20, 2017

m-kuhn commented Dec 20, 2017 • edited Loading

anitagraser commented Jan 2, 2018

SrNetoChan commented Jan 2, 2018 • edited Loading

SrNetoChan commented Jan 2, 2018

m-kuhn commented Jan 3, 2018

m-kuhn commented Jan 3, 2018 • edited Loading

DelazJ commented Jan 16, 2018

DelazJ commented Feb 17, 2018

DelazJ commented Feb 17, 2018

anitagraser commented Dec 10, 2017 •

edited by DelazJ

Loading

anitagraser Dec 17, 2017 •

edited

Loading

m-kuhn commented Dec 20, 2017 •

edited

Loading

SrNetoChan commented Jan 2, 2018 •

edited

Loading

m-kuhn commented Jan 3, 2018 •

edited

Loading