<html>
<head>
<base href="https://bugs.documentfoundation.org/">
</head>
<body><table border="1" cellspacing="0" cellpadding="8">
<tr>
<th>Bug ID</th>
<td><a class="bz_bug_link
bz_status_UNCONFIRMED "
title="UNCONFIRMED - Suggested improvement to Help files that define syntax of Calc functions"
href="https://bugs.documentfoundation.org/show_bug.cgi?id=131354">131354</a>
</td>
</tr>
<tr>
<th>Summary</th>
<td>Suggested improvement to Help files that define syntax of Calc functions
</td>
</tr>
<tr>
<th>Product</th>
<td>LibreOffice
</td>
</tr>
<tr>
<th>Version</th>
<td>6.4.0.3 release
</td>
</tr>
<tr>
<th>Hardware</th>
<td>All
</td>
</tr>
<tr>
<th>OS</th>
<td>All
</td>
</tr>
<tr>
<th>Status</th>
<td>UNCONFIRMED
</td>
</tr>
<tr>
<th>Severity</th>
<td>enhancement
</td>
</tr>
<tr>
<th>Priority</th>
<td>medium
</td>
</tr>
<tr>
<th>Component</th>
<td>Calc
</td>
</tr>
<tr>
<th>Assignee</th>
<td>libreoffice-bugs@lists.freedesktop.org
</td>
</tr>
<tr>
<th>Reporter</th>
<td>stevemfanning.wh@gmail.com
</td>
</tr></table>
<p>
<div>
<pre>As a member of the Documentation Team, I have been investigating how we can
improve the documentation associated with Calc's 500+ functions.
I have noted that there is an inconsistency across the help files with regards
to defining the syntax of a function call. In most cases the basic syntax is
expressed as the name of the function, followed by an open round bracket,
followed by a list of the parameter names separated by semi-colons, followed by
a close round bracket. For example:
- NOW()
- ABS(Number)
- ATAN2(NumberX; NumberY)
There are a small number of function-related help topics which omit any such
information but I will raise a separate bug to cover these.
This basic syntax works well and is, I believe, helpful for the user. However
some help topics extend this syntax to place square brackets around the names
of optional parameters (examples of such functions include AGGREGATE, SUMIFS,
FORECAST.ETS.PI.MULT, SWITCH, GETPIVOTDATA). Other help topics which do not
adopt this approach usually state the nature of the parameter (required or
optional) in its associated text description - there are however cases in which
no statement is made.
I feel that consistency would be highly desirable and so it would be better if
we adopted a consistent approach to syntax specification across all help topics
for Calc's functions. My preferred option would be to update the help files as
necessary to use the square brackets throughout (even if the associated text
already states that a parameter is optional). The square brackets approach
provides information at a glance, without visually searching through text.
I realize that there would be significant work to rationalize this across the
help files but I volunteer to do it (subject only to Olivier Hallot finding
time to provide me with a tutorial on the mechanics of editing file files!).</pre>
</div>
</p>
<hr>
<span>You are receiving this mail because:</span>
<ul>
<li>You are the assignee for the bug.</li>
</ul>
</body>
</html>