[Libreoffice-bugs] [Bug 131354] New: Suggested improvement to Help files that define syntax of Calc functions

[bugzilla-daemon at bugs.documentfoundation.org]

https://bugs.documentfoundation.org/show_bug.cgi?id=131354

            Bug ID: 131354
           Summary: Suggested improvement to Help files that define syntax
                    of Calc functions
           Product: LibreOffice
           Version: 6.4.0.3 release
          Hardware: All
                OS: All
            Status: UNCONFIRMED
          Severity: enhancement
          Priority: medium
         Component: Calc
          Assignee: libreoffice-bugs at lists.freedesktop.org
          Reporter: stevemfanning.wh at gmail.com

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!).

-- 
You are receiving this mail because:
You are the assignee for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/libreoffice-bugs/attachments/20200315/784fd156/attachment.htm>