Skip to content

Add section about the task element #233 #296

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add section about the task element #233 #296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a372a2
Add section about the task element #233
dariavladykina May 15, 2024
1909df8
Update xml/docu_styleguide.structure.xml
dariavladykina May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion xml/docu_styleguide.smartdocs.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@ ultrashort description for social media, max. 55 chars</meta>
</para>
<para>Update revision history regularly, mentioning most important changes to
your document when you amend or rework it. The data you enter as revision history
is used as meta data.
is used as metadata.
The <quote>Revision History</quote> text is available as a link before the abstract and opens up in its individual
page. Keep in mind the following rules:</para>
<itemizedlist>
Expand Down
60 changes: 60 additions & 0 deletions xml/docu_styleguide.structure.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3145,6 +3145,66 @@ Entire hard disks are listed as devices without numbers, such as
</table>
</sect2>

<sect2 xml:id="sec-task-element">
<title>Task elements</title>
<para>
The <tag>task</tag> element encapsulates a procedure, providing an explicit
location for summary information, identifying prerequisites for
the task, examples and pointers to related information. Use it to
present instructions or steps required to perform a specific task.</para>
<example xml:id="ex-task-source">
<title>Example of a task element (source)</title>
<screen>
&lt;task xml:id="task.example"&gt;
&lt;title&gt;An example task&lt;/title&gt;
&lt;tasksummary&gt;
&lt;para&gt;This is the summary of this task.&lt;/para&gt;
&lt;/tasksummary&gt;
&lt;taskprerequisites&gt;
&lt;para&gt;This contains the requirements.&lt;/para&gt;
&lt;/taskprerequisites&gt;
Comment on lines +3160 to +3165
Copy link
Contributor

@tomschr tomschr May 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we require a <title> for <tasksummary> and <taskprerequisites>?

Copy link
Contributor

@jfaltenbacher jfaltenbacher May 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in my experience <tasksummary> is only a repetition of the title itself in most cases, having it as an optional element is sufficient

<taskprerequisites> should have a default title like 'Prerequisites'

Copy link
Contributor Author

@dariavladykina dariavladykina May 21, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think so. "Requirements" are rendered as a headline by the style sheets, and the summary does not really need another title.

&lt;procedure&gt;
&lt;title&gt;Description of useful steps&lt;/title&gt;
&lt;step&gt;
&lt;para&gt;The first step&lt;/para&gt;
&lt;/step&gt;
&lt;step&gt;
&lt;para&gt;The second step&lt;/para&gt;
&lt;/step&gt;
&lt;/procedure&gt;
&lt;taskrelated&gt;
&lt;para&gt;Add task-related information.&lt;/para&gt;
&lt;/taskrelated&gt;
&lt;/task&gt;
</screen>
</example>

<example xml:id="ex-task-output">
<title>Example of a task element (output)</title>
<task xml:id="ex-TASK-TITLE">
<title>An example task</title>
<tasksummary>
<para>This is the summary of this task.</para>
</tasksummary>
<taskprerequisites>
<para>This contains the requirements.</para>
</taskprerequisites>
<procedure>
<title>Description of useful steps</title>
<step>
<para>The first step</para>
</step>
<step>
<para>The second step</para>
</step>
</procedure>
<taskrelated>
<para>Add task-related information.</para>
</taskrelated>
</task>
</example>
</sect2>

<sect2 xml:id="sec-ui-item-markup">
<title>User interface items</title>
<para>
Expand Down