From 9077a2887221677690282917c66c7af8e3e37121 Mon Sep 17 00:00:00 2001
From: Steve Fanning <stevemfanning@yahoo.co.uk>
Date: Fri, 5 Nov 2021 12:28:17 +0200
Subject: Improve Example section of help description for Calc's SUM() function

The ability to use SUM in an array formula is important but the help description of an example array formula is uncharacteristically long. Now that the wiki has a more specific example, it is appropriate to shorten the Example section of this help topic.

Also moved SUM description to its own XHP file.

Change-Id: Ic062686c53a1ae8b81100e2b49781aaa79e6ee50
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/124696
Tested-by: Jenkins
Reviewed-by: Eike Rathke <erack@redhat.com>
Reviewed-by: Olivier Hallot <olivier.hallot@libreoffice.org>
---
 AllLangHelp_scalc.mk              |  1 +
 source/text/scalc/01/04060106.xhp | 15 ++++--------
 source/text/scalc/01/func_sum.xhp | 48 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 10 deletions(-)
 create mode 100644 source/text/scalc/01/func_sum.xhp

diff --git a/AllLangHelp_scalc.mk b/AllLangHelp_scalc.mk
index 0bc4bd0cdb..617223bfed 100644
--- a/AllLangHelp_scalc.mk
+++ b/AllLangHelp_scalc.mk
@@ -253,6 +253,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,scalc,\
     helpcontent2/source/text/scalc/01/func_second \
     helpcontent2/source/text/scalc/01/func_skewp \
     helpcontent2/source/text/scalc/01/func_searchb \
+    helpcontent2/source/text/scalc/01/func_sum \
     helpcontent2/source/text/scalc/01/func_sumifs \
     helpcontent2/source/text/scalc/01/func_switch \
     helpcontent2/source/text/scalc/01/func_textjoin \
diff --git a/source/text/scalc/01/04060106.xhp b/source/text/scalc/01/04060106.xhp
index acd376eae9..a245b9d28f 100644
--- a/source/text/scalc/01/04060106.xhp
+++ b/source/text/scalc/01/04060106.xhp
@@ -1033,16 +1033,11 @@
 <embed href="text/scalc/01/ful_func.xhp#number255"/>
 <embed href="text/scalc/01/common_func.xhp#datenumbersequencenote"/>
 <embed href="text/scalc/01/common_func.xhp#sectionexample"/>
-<paragraph id="par_id3163704" role="paragraph" xml-lang="en-US">If you enter the numbers <item type="input">2</item>; <item type="input">3 </item>and <item type="input">4</item> in the Number 1; 2 and 3 text boxes, 9 will be returned as the result.</paragraph>
-<paragraph id="par_id3151740" role="paragraph" xml-lang="en-US"><item type="input">=SUM(A1;A3;B5)</item> calculates the sum of the three cells. <item type="input">=SUM (A1:E10)</item> calculates the sum of all cells in the A1 to E10 cell range.</paragraph>
-<paragraph id="par_id3151756" role="paragraph" xml-lang="en-US">Conditions linked by AND can be used with the function SUM() in the following manner:</paragraph>
-<paragraph id="par_id3151774" role="paragraph" xml-lang="en-US">Example assumption: You have entered invoices into a table. Column A contains the date value of the invoice, column B the amounts. You want to find a formula that you can use to return the total of all amounts only for a specific month, e.g. only the amount for the period &gt;=2008-01-01 to &lt;2008-02-01. The range with the date values covers A1:A40, the range containing the amounts to be totaled is B1:B40. C1 contains the start date, 2008<item type="input">-01-01</item>, of the invoices to be included and C2 the date, 2008<item type="input">-02-01</item>, that is no longer included.</paragraph>
-<paragraph id="par_id3151799" role="paragraph" xml-lang="en-US">Enter the following formula as an array formula:</paragraph>
-<paragraph id="par_id3151813" role="paragraph" xml-lang="en-US"><item type="input">=SUM((A1:A40&gt;=C1)*(A1:A40&lt;C2)*B1:B40)</item></paragraph>
-<paragraph id="par_id3151828" role="paragraph" xml-lang="en-US">In order to enter this as an array formula, you must press the Shift<switchinline select="sys"><caseinline select="MAC">+Command
-</caseinline><defaultinline>+ Ctrl</defaultinline></switchinline>+ Enter keys instead of simply pressing the Enter key to close the formula. The formula will then be shown in the <emph>Formula</emph> bar enclosed in braces.</paragraph>
-<paragraph id="par_id3151869" role="paragraph" xml-lang="en-US">{=SUM((A1:A40&gt;=C1)*(A1:A40&lt;C2)*B1:B40)}</paragraph>
-<paragraph id="par_id3151884" role="paragraph" xml-lang="en-US">The formula is based on the fact that the result of a comparison is 1 if the criterion is met and 0 if it is not met. The individual comparison results will be treated as an array and used in matrix multiplication, and at the end the individual values will be totaled to give the result matrix.</paragraph>
+<paragraph id="par_id3163704" role="paragraph" xml-lang="en-US"><input>=SUM(2;3;4)</input> returns 9.</paragraph>
+<paragraph id="par_id3151740" role="paragraph" xml-lang="en-US"><item type="input">=SUM(A1;A3;B5)</item> calculates the sum of the three cells.</paragraph>
+<paragraph id="par_id931636109030406" role="paragraph" xml-lang="en-US"><item type="input">=SUM(A1:E10)</item> calculates the sum of all cells in the A1 to E10 cell range.</paragraph>
+<paragraph id="par_id3151756" role="paragraph" xml-lang="en-US">A formula such as <input>=SUM((A1:A40&gt;=C1)*(A1:A40&lt;C2)*B1:B40)</input> may be entered as an <link href="text/scalc/01/04060107.html#hd_id3148474" name="ARRAY_FORMULA">array formula</link> by pressing the Shift<switchinline select="sys"><caseinline select="MAC">+Command</caseinline><defaultinline>+Ctrl</defaultinline></switchinline>+Enter keys instead of simply pressing the Enter key to finish entering the formula. The formula will then be shown in the Formula bar enclosed in braces and operates by multiplying corresponding elements of the arrays together and returning their sum.</paragraph>
+<tip id="par_id661636108218550">Refer to the <link href="https://wiki.documentfoundation.org/Documentation/Calc_Functions/SUM" name="SUM_Wiki">SUM</link> wiki page for more details about this function.</tip>
 </section>
 
 <section id="Section15">
diff --git a/source/text/scalc/01/func_sum.xhp b/source/text/scalc/01/func_sum.xhp
new file mode 100644
index 0000000000..389c0bcc48
--- /dev/null
+++ b/source/text/scalc/01/func_sum.xhp
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<helpdocument version="1.0">
+<!--
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+-->
+
+<meta>
+  <topic id="calcfuncsum" indexer="include" status="PUBLISH">
+    <title id="tit" xml-lang="en-US">SUM Function</title>
+    <filename>/text/scalc/01/func_sum.xhp</filename>
+  </topic>
+</meta>
+<body>
+  <section id="func_sum">
+    <bookmark id="bm_id691636401721449" xml-lang="en-US" branch="hid/SC_HID_FUNC_SUMME" localize="false"/>
+    <bookmark xml-lang="en-US" branch="index" id="id431636401649762">
+      <bookmark_value>SUM function</bookmark_value>
+      <bookmark_value>adding;numbers in cell ranges</bookmark_value>
+    </bookmark>    
+    <h1 id="hd_id121636398275790"><variable id="sum_head"><link href="/text/scalc/01/func_sum.xhp" name="function SUM">SUM</link></variable></h1>
+    <paragraph id="par_id491636401806866" role="paragraph"><variable id="func_sum_desc"><ahelp hid=".">Adds a set of numbers.</ahelp></variable></paragraph>
+  </section>
+
+  <embed href="text/scalc/01/common_func.xhp#sectionsyntax"/>
+  <paragraph id="par_id3163656" role="code" xml-lang="en-US">SUM(<embedvar href="text/scalc/01/ful_func.xhp#number255_1" markup="keep"/>)</paragraph>
+  <embed href="text/scalc/01/ful_func.xhp#number255"/>
+  <embed href="text/scalc/01/common_func.xhp#datenumbersequencenote"/>
+  <embed href="text/scalc/01/common_func.xhp#sectionexample"/>
+  <paragraph id="par_id3163704" role="paragraph" xml-lang="en-US"><input>=SUM(2;3;4)</input> returns 9.</paragraph>
+  <paragraph id="par_id3151740" role="paragraph" xml-lang="en-US"><item type="input">=SUM(A1;A3;B5)</item> calculates the sum of the three cells.</paragraph>
+  <paragraph id="par_id931636109030406" role="paragraph" xml-lang="en-US"><item type="input">=SUM(A1:E10)</item> calculates the sum of all cells in the A1 to E10 cell range.</paragraph>
+  <paragraph id="par_id3151756" role="paragraph" xml-lang="en-US">A formula such as <input>=SUM((A1:A40&gt;=C1)*(A1:A40&lt;C2)*B1:B40)</input> may be entered as an <link href="text/scalc/01/04060107.html#hd_id3148474" name="ARRAY_FORMULA">array formula</link> by pressing the Shift<switchinline select="sys"><caseinline select="MAC">+Command</caseinline><defaultinline>+Ctrl</defaultinline></switchinline>+Enter keys instead of simply pressing the Enter key to finish entering the formula. The formula will then be shown in the Formula bar enclosed in braces and operates by multiplying corresponding elements of the arrays together and returning their sum.</paragraph>
+  <tip id="par_id661636108218550">Refer to the <link href="https://wiki.documentfoundation.org/Documentation/Calc_Functions/SUM" name="SUM_Wiki">SUM</link> wiki page for more details about this function.</tip>
+
+  <section id="relatedtopics">
+    <paragraph id="par_id381636401121931" role="paragraph" localize="false">
+	  <embedvar href="text/scalc/01/04060106.xhp#sumif_head"/>,
+	  <embedvar href="text/scalc/01/func_sumifs.xhp#sumifs_head"/>
+    </paragraph>
+  </section>  
+  
+</body>
+</helpdocument>
\ No newline at end of file
-- 
cgit