Git commit 860ee0804e43e6f1030d97a671a2351cd66155b0 by Burkhard Lück. Committed on 26/05/2016 at 18:19. Pushed by lueck into branch 'master'.
add sect for project plugin REVIEW:127998 M +0 -42 doc/kate/menus.docbook M +332 -4 doc/kate/plugins.docbook A +- -- doc/kate/project-completition.png A +- -- doc/kate/project-configure.png A +- -- doc/kate/project-current-analysis.png A +- -- doc/kate/project-quickopen.png A +- -- doc/kate/project-search.png A +- -- doc/kate/project-view.png A +- -- doc/kate/snippets-repository.png http://commits.kde.org/kate/860ee0804e43e6f1030d97a671a2351cd66155b0 diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook index 1c95b3e..eb9d684 100644 --- a/doc/kate/menus.docbook +++ b/doc/kate/menus.docbook @@ -1195,48 +1195,6 @@ Show Word Count -> Displays the number of words and characters in the document a </sect1> -<sect1 id="projects-menu"> -<title>The Projects Menu</title> - -<para>The <guimenu>Projects</guimenu> menu allows you to switch between -currently open projects. It is displayed by the Project plugin.</para> - -<variablelist> -<title>Menu Items</title> - -<!--FIXME: these shortcuts conflict with the preexisting Build plugin - https://bugs.kde.org/show_bug.cgi?id=328170 --> - -<varlistentry id="projects-back"> -<term><menuchoice> -<shortcut> -<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo> -</shortcut> -<guimenu>Projects</guimenu> -<guimenuitem>Back</guimenuitem> -</menuchoice></term> -<listitem> -<para>Switch to the previous project.</para> -</listitem> -</varlistentry> - -<varlistentry id="projects-forward"> -<term><menuchoice> -<shortcut> -<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo> -</shortcut> -<guimenu>Projects</guimenu> -<guimenuitem>Forward</guimenuitem> -</menuchoice></term> -<listitem> -<para>Switch to the next project.</para> -</listitem> -</varlistentry> - -</variablelist> - -</sect1> - <sect1 id="bookmarks-menu"> <title>The Bookmarks Menu</title> diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook index b84db72..8a63444 100644 --- a/doc/kate/plugins.docbook +++ b/doc/kate/plugins.docbook @@ -74,7 +74,7 @@ simple &gdb; frontend</para> <para>Open Header - Opens the corresponding .h/[.cpp|.c] file</para> </listitem> <listitem> -<para>Project Plugin - Project plugin for kate</para> +<para><link linkend="kate-application-plugin-projects">Project Plugin</link> - Project plugin for kate</para> </listitem> <listitem> <para>Replicode</para> @@ -976,9 +976,337 @@ https://kate-editor.org/2014/02/20/lumen-a-code-completion-plugin-for-the-d-prog <!--FIXME Open header menu File Open header--> -<!--FIXME Project -https://kate-editor.org/2012/11/02/using-the-projects-plugin-in-kate/ -Projects Previous Next Goto--> +<sect1 id="kate-application-plugin-projects"> +<!--https://kate-editor.org/2012/11/02/using-the-projects-plugin-in-kate --> + +<title>Project Plugin</title> + +<sect2 id="project-intro"> +<title>Introduction</title> + +<para>The basic idea of the Project plugin is to have a structured list of +files belonging to the project with the following properties:</para> + +<orderedlist> +<listitem><para>Provide a structured view of the files</para></listitem> +<listitem><para>Make it easy and very fast to open and switch projects</para></listitem> +<listitem><para>Support search and replace for a project</para></listitem> +<listitem><para>Provide simple auto completion</para></listitem> +<listitem><para>Make it simple to quickly open files in the project</para></listitem> +<listitem><para>Support for building the project</para></listitem> +</orderedlist> +</sect2> + +<sect2 id="project-view"> +<title>Structured View of the Files</title> + +<para>Once the Project plugin is loaded in the &kate; configuration page, open a file +in a project and a sidebar +appears that lists all projects as well as the project files as follows:</para> + +<screenshot id="screenshot-project-view"> +<screeninfo>Project View</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="project-view.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>As you can see, the currently active project is <quote>Kate</quote>, and it’s contents is +listed in the tree view. Clicking on files in the tree view opens the file in the +editor. Further, a context menu is provided with which you can open files with +other applications, such as a <filename class="extension">.ui</filename> file with Qt Designer.</para> +<para>You can filter the items by typing parts of the file name you are looking for into the search bar +at the bottom of the list.</para> +</sect2> + +<sect2 id="project-switch"> +<title>Switching Projects</title> + +<para>The idea is that you never have to open a project manually, this is even not +supported at all. Hence, what happens if you open a file, the Project plugin quickly +scans the folder and its parent folders for a <filename>.kateproject</filename> file. If found, the project +is automatically loaded.</para> + +<para>Furthermore, if you open another document in &kate;, that belongs to another project, +the Project plugin automatically switches the current project. So intuitively, always the +correct project is active. Of course, you can also switch the currently active project +using the combo box.</para> + +</sect2> + +<sect2 id="project-search-replace"> +<title>Search and Replace in Projects</title> + +<para>&kate; has a Search and Replace plugin that shows up in the +bottom sidebar. If a project is loaded, open the Search and Replace sidebar, +and switch to the mode to search and replace in the current project:</para> + +<screenshot id="screenshot-projects-search"> +<screeninfo>Search in Projects</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="projects-search.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect2> + +<sect2 id="project-autocompletition"> +<title>Simple Auto Completion</title> + +<para>With the knowledge of all files belonging to a project, the Project plugin provides +simple auto completion facilities based on CTags. If a project is initially opened, CTags +parses all project files in a background thread and saves the CTags information to +<filename class="directory">/tmp</filename>. This file then is used to populate the auto +completion popup in &kate;.</para> + +<para>In contrast, without this auto completion, &kate; is only capable of showing auto +completion items based on the words in the current file. So the auto completion provided +by the Project plugin is much more powerful.</para> + +<screenshot id="screenshot-completion-search"> +<screeninfo>Completion in Projects</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="project-completition.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>If CTags is missing, a passive popup warns you about this issue. It is also noteworthy, +that the CTags file in <filename class="directory">/tmp</filename> is cleaned up when &kate; +exits, so the plugin does not pollute any folder with unwanted files.</para> + +</sect2> + +<sect2 id="project-quickopen"> +<title>Quick Opening Files</title> + +<para>As clicking on files in the tree view is not the fastest way to open a file, &kate; +provides a built-in quick open mechanism you can activate with +<keycombo action="simul">&Ctrl;&Alt;<keycap>O</keycap></keycombo>. +What you the get is a list like this:</para> + +<screenshot id="screenshot-project-quickopen"> +<screeninfo>Quick Open</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="project-quickopen.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>You can filter by typing parts of the file name you are looking for, and you can +also navigate with the arrow keys and page up/down through the list. +Hitting &Enter; activates the selected file, while &Esc; hides the quick open view again.</para> + +<para>Further, the quick open remembers the previous file. So when you change to the +quick open view the previously activated file is automatically selected and you just +need to hit &Enter;, which comes very handy at times.</para> + +</sect2> + +<sect2 id="project-build"> +<title>Support for Building the Project</title> + +<para>Another feature is to have support for the <link linkend="projects-build-support">Build Plugin</link>, +so that it automatically is configured correctly.</para> + +</sect2> + +<sect2 id="project-create"> +<title>Creating Projects</title> + +<sect3 id="project-autoload"> +<!--https://kate-editor.org/2014/10/12/autoloading-projects-plugin-kate-5/--> +<title>Loading Projects Automatically</title> + +<para>The Project plugin has an auto-loading feature. You can read the file list from +the version control system. To this end, auto-loading for the respective version control +system needs to be enabled in the settings (enabled by default): +</para> + +<screenshot id="screenshot-project-configure"> +<screeninfo>Project Plugin Configuration</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="project-configure.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect3> + +<sect3 id="project-manual"> +<title>Creating Projects Manually</title> +<para> +You just have to create a <filename>.kateproject</filename> file in the root folder of the project. +For instance, the <quote>Kate</quote> <filename>.kateproject</filename> file looks like this: +</para> + +<screen> +{ + "name": "Kate" +, "files": [ { "git": 1 } ] +} +</screen> + +<para>The file content is written in JSON syntax. The project name is <quote>Kate</quote>, and +the files contained in should be read from git. +</para> + +<para> +Also supported instead of <literal>git</literal> is subversion through <literal>svn</literal> and +mercurial through <literal>hg</literal>. +If you do not want to read from a version control system, you can tell it to recursively +load files from directories as follows: +</para> + +<screen> +{ + "name": "Kate" +, "files": [ { "directory": "kate", "filters": ["*.cpp", "*.h", "*.ui", "CMakeLists.txt", "Find*.cmake"], "recursive": 1 } ] +} +</screen> + +<para> +Here, subfolders and filters define what’s part of the project. +You can also mix version control and files based on filters. +</para> + +<para id="projects-build-support">If you want to add support for the Build plugin, you could write a +<filename>.kateproject</filename> like this:</para> + +<screen> +{ + "name": "Kate" +, "files": [ { "git": 1 } ] +, "build": { + "directory": "build" + , "build": "make all" + , "clean": "make clean" + , "install": "make install" + } +} +</screen> + +</sect3> + +</sect2> + +<sect2 id="project-current"> +<title>Current Project</title> + +<para>Using <menuchoice><shortcut><keycombo action="simul">&Alt;<keycap>1</keycap></keycombo></shortcut> +<guimenu>Projects</guimenu><guimenuitem>Go To</guimenuitem></menuchoice> you can open the +<guilabel>Current Project</guilabel> view at the bottom of the editor window with four tabs:</para> + +<screenshot id="screenshot-project-current"> +<screeninfo>Current Project</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="project-current-analysis.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<variablelist> + +<varlistentry> +<term> +<guimenu>Terminal</guimenu> +</term> +<listitem> +<para>A <link linkend="kate-application-plugin-konsole">Terminal emulator</link> starting in the +root folder of the project.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<guimenu>Code Index</guimenu> +</term> +<listitem> +<para>Entering characters into the search bar will start the search and display matching names +of functions, classes, symbols &etc; together with kind, filename and line number.</para> +<para>Select an item in the list to jump to the corresponding line in the source file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<guimenu>Code Analysis</guimenu> +</term> +<listitem> +<para>Click <guilabel>Start Analysis</guilabel> to run a static code analysis for the C and C++ +using <command>cppcheck</command> and to generate a report showing filename, line number, severity +(style, warning &etc;) and the issue found.</para> +<para>Select an item in the list to jump to the corresponding line in the source file.</para> +</listitem> +</varlistentry> +<!--FIXME options for cppcheck? configurable?--> +<varlistentry> +<term> +<guimenu>Notes</guimenu> +</term> +<listitem> +<para>Text entered in this tab will be saved in the file +<filename><replaceable>projectname</replaceable>.kateproject.notes</filename>.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="projects-menu"> +<title>The Projects Menu</title> + +<para>The <guimenu>Projects</guimenu> menu allows you to switch between +currently open projects. It is displayed by the Project plugin.</para> + +<variablelist> + +<!--FIXME: these shortcuts conflict with the preexisting Build plugin + https://bugs.kde.org/show_bug.cgi?id=328170 --> + +<varlistentry id="projects-back"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo> +</shortcut> +<guimenu>Projects</guimenu> +<guimenuitem>Back</guimenuitem> +</menuchoice></term> +<listitem> +<para>Switch to the previous project.</para> +</listitem> +</varlistentry> + +<varlistentry id="projects-forward"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo> +</shortcut> +<guimenu>Projects</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice></term> +<listitem> +<para>Switch to the next project.</para> +</listitem> +</varlistentry> + +<varlistentry id="projects-goto"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>1</keycap></keycombo> +</shortcut> +<guimenu>Projects</guimenu><guimenuitem>Go To</guimenuitem> +</menuchoice></term> +<listitem> +<para>Ppen the <guilabel>Current Project</guilabel> view at the bottom of the editor window.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> +<!-- +context menu Project->Lookup:xxx +--> + +</sect1> <!--FIXME Replicode Projects Replicode run / stop--> diff --git a/doc/kate/project-completition.png b/doc/kate/project-completition.png new file mode 100644 index 0000000..c78e61b Binary files /dev/null and b/doc/kate/project-completition.png differ diff --git a/doc/kate/project-configure.png b/doc/kate/project-configure.png new file mode 100644 index 0000000..afb14a5 Binary files /dev/null and b/doc/kate/project-configure.png differ diff --git a/doc/kate/project-current-analysis.png b/doc/kate/project-current-analysis.png new file mode 100644 index 0000000..ab2dc50 Binary files /dev/null and b/doc/kate/project-current-analysis.png differ diff --git a/doc/kate/project-quickopen.png b/doc/kate/project-quickopen.png new file mode 100644 index 0000000..1c0c6e5 Binary files /dev/null and b/doc/kate/project-quickopen.png differ diff --git a/doc/kate/project-search.png b/doc/kate/project-search.png new file mode 100644 index 0000000..94d686b Binary files /dev/null and b/doc/kate/project-search.png differ diff --git a/doc/kate/project-view.png b/doc/kate/project-view.png new file mode 100644 index 0000000..194225a Binary files /dev/null and b/doc/kate/project-view.png differ diff --git a/doc/kate/snippets-repository.png b/doc/kate/snippets-repository.png new file mode 100644 index 0000000..960df51 Binary files /dev/null and b/doc/kate/snippets-repository.png differ _______________________________________________ kde-doc-english mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-doc-english
