Skip to content
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.

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

Implement task element? #233

Open
dariavladykina opened this issue Nov 21, 2022 · 7 comments
Open

Implement task element? #233

dariavladykina opened this issue Nov 21, 2022 · 7 comments

Comments

@dariavladykina
Copy link
Contributor

dariavladykina commented Nov 21, 2022

There is a suggestion in the Style sheets repo to implement the task element in our style sheets. Its role in the document is similar to that of a sect and it is reportedly relevant for Smart Docs, too.
Shall we adopt it?

@dariavladykina
Copy link
Contributor Author

Our friendly DocBook designer suggests to make the following children elements of task required ones:
tasksummary and taskprerequisites.

Please see the example (Summary and Requirements):
image

@dariavladykina
Copy link
Contributor Author

Note: we should also list the usage of this element in DSG

@janajaeger
Copy link
Contributor

Note: we should also list the usage of this element in DSG

I agree to all that's said above. However, do we want to use this for each and every task in our docs or just where we have a larger task that is broken into subtasks that need to be referred to?

@jfaltenbacher
Copy link
Contributor

jfaltenbacher commented Feb 9, 2023

I like the idea. tasksummary makes sense. requirements may not always apply, so I would not make this element mandatory

@jfaltenbacher
Copy link
Contributor

for me it is still: great to have but I would not make it mandatory

@cwickert
Copy link
Member

For reference, here is the DocBook element definition from https://tdg.docbook.org/tdg/5.1/task.html

<article xmlns='http://docbook.org/ns/docbook'>
  <title>Example task</title>
  <task>
    <title>Changing a light bulb</title>
    <tasksummary>
      <para>How to change a light bulb</para>
    </tasksummary>
    <taskprerequisites>
      <para>Make sure you have a new light bulb.</para>
      <para>Make sure you have turned off the light switch.</para>
    </taskprerequisites>
    <procedure>
      <step><para>Remove the old light bulb.</para></step>
      <step><para>Insert the new light bulb.</para></step>
      <step><para>Turn on the new light bulb.</para></step>
      <step><para>Throw away the old light bulb.</para></step>
    </procedure>
  </task>

@cwickert
Copy link
Member

I agree with @jfaltenbacher that taskprerequisites should be optional.

Additionally, I think that we should change Requirements to Prerequisites so that elements and display match.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants