Initial fix for Issue #403 (Pl_Editor)

[evanshultz]

Moved and re-named sections without changing content; fixed link for page_property_2.png image.

Recall that, like PR #407 , only the section names and section flow should be reviewed now. I've made no effort to change the content of sections, but I will embark on that next with the goal being to avoid changing text (for translation reasons) where possible. Right now, just look at the sections and other patches will be submitted for content later before the PR is ready to merge.

My thoughts/questions:

1. Is the "Basic layout elements" section helpful? I don't think so. Any unique information could be moved to the relevant section for that element type at the bottom.
2. I question if the "Context menu" section has any value to learning/using Pl Editor.
3. Under the "Adding elements" section, should the main subsections start with "Adding" as well?
4. Rotating is so common and simple that I'm not sure it has any benefit. Repeating is a nice tip, at least, but the rotation section seems superfluous to me.

[kinichiro]

I built your PR for Pl_editor to PDF, is that your structure, right ?

1 Introduction
  1.1 Basic layout elements
  1.2 Coordinates defintion and reference corners

2 Interface
  2.1 Main window
  2.2 Main toolbar
  2.3 Status bar
  2.4 Left window
  2.5 Right window
  2.6 Keyboard commands
  2.7 Mouse commands
  2.8 Context menu
  2.9 Item selection

3 Adding elements
  3.1 Adding lines and rectangles
  3.2 Adding text
    3.2.1 Page 1 text
    3.2.2 Format symbols
    3.2.3 Multi-line text
    3.2.4 Full-size text
  3.3 Adding logos
  3.4 Adding image bitmaps
  3.5 Rotating elements
  3.6 Repeating elements

I agree your structure as I mentioned before https://github.com/KiCad/kicad-doc/issues/403#issuecomment-229249204 .
But, I feel "2.9 Item selection" should go under "3 Adding elements",
since that sections is about operations not Interface, I feel.

1 Is the "Basic layout elements" section helpful? I don't think so...

Do you mean "Basic layout elements" section should not be top of the doc, but should move to under "3 Adding elements" ?

2 I question if the "Context menu" section has any value to learning/using Pl Editor.

This is a reference manual for Pl_editor, so available functionality should be described,
though, indeed it has less information for users, now.
We couldn't have much time to improve for some manuals, such as idf_exporter and this one,
since maintaining manuals of primary programs (Eeschema and Pcbnew) was tough enough.

3 Under the "Adding elements" section, should the main subsections start with "Adding" as well?

That might funny :-) Is there any good expressions for this ?

4 Rotating is so common and simple that I'm not sure it has any benefit. ...

Do you want to add more interesting tips here ?
I think it is good.

Best regards,

[evanshultz]

@kinichiro
Yes, you got the basic structure. Thanks for checking it out.

I understand what you mean, where 2 is about the interface and 3 is about doing something. I put Item Selection into section 2 because it applies to existing elements and not adding any elements. That still makes the most sense to me. Does anyone else have an opinion?

1 To me Basic Layout Elements can be removed. They each have their own subsection in section 3 and that existing chunk of text just didn't hold value for me. Any unique bits of text can find a different home elsewhere in the document. I kept the text to have this discussion instead of deleting it.

2 I feel the context menu is obvious and users don't need to have a separate section just to list the items there. When describing the functions of the tool elsewhere in the program the context menu will be covered without adding redundant text.

3 I should be more clear. Instead of:
Adding elements
Adding lines and rectanges
Adding text

Should we have:
Adding elements
Lines and rectangles
Text

Since the whole section is about adding, I think removing the extra "Adding" at the beginning of each section is acceptable. But if viewed section-by-section instead of the outline, it may be more confusing because the section title could be lost. I was conservative by keeping "Adding" but wanted everybody to chime in on their thoughts.

So... what say ye? If we can approve this outline, with the section retention/removal and naming above, then I will dig into the meat of this document and update the text.

[evanshultz]

@ciampix @kinichiro @nickoe
http://ci.kicad-pcb.org/job/kicad-doxygen/ws/Documentation/doxygen/html/v5_road_map.html mentions improving the translations. My PR above is, I believe, improving the document flow after which I'll go through it and edit the text. While I do want to help, and have every intention of being a productive member of the documentation team, this PR needs to be addressed first. Please provide feedback to get this PR unstuck so progress can be made. If you don't feel this PR is moving in the right direction, then let's have a conversation so that I can volunteer my time productively improving KiCad.

[ciampix]

Bump. This is very old and I apologize for this. I want to clear this up. I confess I did look into any of these improvement. Let's see to this and close this up!

[ciampix]

For a start I absolutely agree with point 1) ...

[ciampix]

For point 2 and 3 I prefer to leave things more verbose instead of concise even if there are some repetitions. For two reasons:

1. repetita iuvant: in a manual to repeat things that appears obvious is something that helps the casual reader that is often the reader because of the common use of these manuals
2. at some point I would like to produce a kind of "context" help function for the applications. I mean to introduce (I still do not know exactly how but I have a vague idea...) a "open the manual on this pointed stuff topic" using the mouse to select the manual section... I'll open a issue on this...

[ciampix]

So, if it is possible to split the 1) from the 2) and 3) I will happily apply 1)

[ciampix]

For point 2 and 3 I prefer to leave things more verbose instead of concise even if there are some repetitions. For two reasons:

1. repetita iuvant: in a manual to repeat things that appears obvious is something that helps the casual reader that is often the reader because of the common use of these manuals
2. at some point I would like to produce a kind of "context" help function for the applications. I mean to introduce (I still do not know exactly how but I have a vague idea...) a "open the manual on this pointed stuff topic" using the mouse to select the manual section... I'll open a issue on this...