[release-notes/gnome-3-26] developers page - add builder material, refine everything else

[Allan Day <allanday src gnome org>]

commit c0130f3affd3bec7f84de2e2eecac3580c56708c
Author: Allan Day <allanpday gmail com>
Date:   Wed Sep 6 17:05:39 2017 +0100

    developers page - add builder material, refine everything else

 help/C/developers.page |   96 +++++++++++++++++++++++++++++------------------
 1 files changed, 59 insertions(+), 37 deletions(-)
---
diff --git a/help/C/developers.page b/help/C/developers.page
index e15bee7..13edbb0 100644
--- a/help/C/developers.page
+++ b/help/C/developers.page
@@ -28,35 +28,57 @@
   <section id="builder">
     <title>Builder</title>
     <media type="image" src="figures/placeholder.png"/>
-    <p><app>Builder</app>, the GNOME integrated development environment (IDE) is even better in 3.26, with 
general improvements as well new features.</p>
+    <p><app>Builder</app>, the GNOME integrated development environment (IDE)
+    has made major advances in 3.26, with general improvements as well as new
+    features. One of the most obvious changes in the new version is a redesigned
+    editor interface. This makes it easier to open and switch between files,
+    terminals and documentation, using either the header popover or the project
+    sidebar. There have been a lot of user interface refinements as part of
+    this work, including document headers which blend into the background.</p>
+    <p>With 3.26 it's now possible to search for symbols throughout your entire
+    project. Selecting a search result jumps to that location, so you can
+    quickly move around your project using only the keyboard. The
+    presentation of search results has also been improved.</p>
+    <media type="image" src="figures/placeholder.png"/>
+    <p>Builder includes a debugging feature for the first time in 3.26. This is
+    an initial preview and is expected to mature in subsequent releases.
+    The debugger allows running your project in debug mode and stepping through
+    to find the source of issues. This includes debugging Flatpak applications.</p>
+    <media type="image" src="figures/placeholder.png"/>
+    <p>Contextual documentation popovers are another new feature for this
+    release. To quickly look up documentation for the code that you're working
+    on, just hover the pointer over the function that you're interested in or
+    place the text cursor within the function and press
+    <key>F2</key> (or <keyseq><key>Shift</key><key>K</key></keyseq> in Vim mode).</p>
+    <p>There are many other improvements in Builder 3.26, including:</p>
+    <list>
+      <item><p>You can now jump from a symbol to where it's defined. To do this, open a context menu for the 
symbol and select <gui>Go to Definition</gui>. Alternatively, place the text cursor within the symbol and 
press <keyseq><key>Alt</key><key>.</key></keyseq> (in Vim mode the equivalent is <key>g</key> 
<key>d</key>).</p></item>
+      <item><p>Word completion now provides better suggestions. This can be activated using 
<keyseq><key>Crtl</key><key>N</key></keyseq> (or <keyseq><key>Crtl</key><key>P</key></keyseq> when in Vim 
mode).</p></item>
+      <item><p>SDKs are no longer automatically downloaded on metered connections, in order to save 
bandwidth.</p></item>
+      <item><p>The Todo plugin has been rewritten to be faster and use less memory.</p></item>
+      <item><p>It is now possible to live preview Syphinx documentation as you edit it. To use this feature, 
select <gui>Open Preview</gui> from the document header.</p></item>
+      <item><p>Keyboard shortcut handling is now more predictable, thanks to a new keyboard shortcut engine. 
This is expected to deliver more improvements in the future.</p></item>
+      <item><p>There has been a lot of attention to detail for 3.26, particularly around the use of 
animations, to create a smoother and more cohesive experience.</p></item>
+      <item><p>Builder's project templates allow you to quickly start a new project. These now use Meson and 
allow specifying JavaScript as the language, so that they follow modern GNOME development 
practices.</p></item>
+      <item><p>Background operations are now displayed in the project popover and can be paused. This is 
used to communicate when source code is being indexed.</p></item>
+      <item><p>More preferences have been added, such as controls for autosave behavior.</p></item>
+    </list>
+    <p>For more information about how to make the most of Builder, <link 
href="http://builder.readthedocs.io/en/latest/";>see the documentation</link> (which has also been improved 
for 3.26!)</p>
 
     <!--
 
-    Language Server Protocol improvements
-    A new keyboard shortcut engine
-    Live code indentation improvements
-    Preview support for Sphinx
-
-
-    Revamp of the user interface elements
-    A new workflow that is "left to right" has landed in the editor as part of the UI cleanup. Sources of 
work exist on the left, work is performed (editing, etc) on the right.
+    Things that were suggested for inclusion but weren't fully understood or didn't seem worth mentioning:
 
-
-
-    New preferences for features such as auto-save
-    New plugins including retab, build notifications, and more
-    Improved application run support
-    Performance improvements
-    Fancy new animations
-    SDKs are no longer automatically downloaded on metered connections
-    Todo plugin has been rewritten to be faster and use less memory
-
-    Animations have been added in places where it makes sense to display to the user what has happened.
-
-    Updated fonts for the overview map
-    New project templates using Meson and adding JavaScript to language options
+     * A symbol resolver based on the code-index allows jumping between source and declarations.
+     * Clang completion provider improvements. Language Server Protocol improvements - now supports find 
references and formater.
+     * Live code indentation improvements.
+     * New retab plugin, build notifications, and more. Possible description of build notifications - 
"System notifications are now shown when a long-running process completes and you are not using Builder (this 
can be controlled from the <gui>Notification of progress</gui> extension."
+     * Improved application run support
+     * Performance improvements
+     * Updated fonts for the overview map
 
     -->
+
   </section>
 
   <section id="flatpak">
@@ -76,25 +98,25 @@
       (OCI) specification.</p></item>
       <item><p><code>flatpak-builder</code> has been separated into its own
       module.</p></item>
-      <item><p>Flatpak applications can now be used with accessibility 
+      <item><p>Flatpak applications can now be used through accessibility
       frameworks.</p></item>
       <item><p>It is now possible to use input methods within Flatpak
       applications.</p></item>
-      <item><p>An experimental peer to peer installation method allows using a
-      range of dynamically available repository sources, including removable
+      <item><p>An experimental peer to peer installation method allows using
+      dynamically available repository sources, including removable
       media or resources on the local network.</p></item>
       <item><p>Flatpak now supports a default language setting, which is used
       to ensure that the correct translations are installed for each
       application.</p></item>
-      <item><p>Various enhancements improve security.</p></item>
+      <item><p>Thera have been a number of enhancements that improve security.</p></item>
       <item><p>Improved progress reporting, particularly for download and
-      installation.</p></item>
+      installation progress.</p></item>
       <item><p>Lots of improvements to the command line tool, including a new
-      <code>flatpak repo</code> command, better presentation of results,
+      <code>flatpak repo</code> command, better presentation of results and
       smarter handling of <code>.flatpakref</code> files.</p></item>
     </list>
     <p><code>flatpak-builder</code>, the tool for generating Flatpak
-    applications, has been split out into its own module and has also had a lot
+    applications, has been split out into its own module and has had a lot
     of improvements. These include:</p>
     <list>
       <item><p>Performance improvements which make building much faster.</p></item>
@@ -102,10 +124,10 @@
       sources.</p></item>
       <item><p>Manifests can specify SDK extensions to be installed for the
       application to build.</p></item>
-      <item><p>A new "add-extension" property makes it easier to create
-      extension points.</p></item>
-      <item><p>The new <code>--from-git=URL</code> option pulls the JSON
-      manifest and related files directly from a Git repository.</p></item>
+      <item><p>A new <code>add-extension</code> property makes it easier to
+      create extension points.</p></item>
+      <item><p><code>--from-git=URL</code> allows pulling the JSON manifest and
+      related files directly from a Git repository.</p></item>
     </list>
     <p>More details can be found in the various
     <link href="https://github.com/flatpak/flatpak/releases";>Flatpak release notes</link>.</p>
@@ -117,8 +139,8 @@
     <p></p>
     <list>
       <item><p>GLib unicode support has been updated to 10.0.0.</p></item>
-      <item><p>In GTK+,gtk3-icon-browser tool can copy the icon name to the clipboard.</p></item>
-      <item><p>GTK+ has also gained support for color emoji. New input hints
+      <item><p>The <code>gtk3-icon-browser</code> tool can now copy the icon name to the 
clipboard.</p></item>
+      <item><p>GTK+ has gained support for color emoji. New input hints
       (<code>GTK_INPUT_HINT_EMOJI</code> and <code>GTK_INPUT_HINT_NO_EMOJI</code>)
       are available and the new emoji picker can be enabled for text entry
       fields with the <code>show-emoji-icon</code> property.</p></item>
@@ -126,7 +148,7 @@
       libcloudprovider</link> is a new library that allows cloud providers to
       integrate with GNOME's file browsing experience. The library can be used
       to display cloud drives in the files sidebar, which is shown in the file
-      chooser dialogs and in the <app>Files</app> application. Each cloud drive
+      chooser dialogs and in the <app>Files</app> application. Each cloud provider
       can display its status (whether it is syncing, and so on) and can also
       specify a menu of options which users can access.</p></item>
     </list>