New updated List of User Guide Issues

[swzCuroverse]

trafficstars

Making a list of existing user guides issues to help with the upcoming Outreachy project and well as help sort out what is left after @kinow recent update work. The new structure ticket maybe have information about where some of these additions will go - can check that here-https://github.com/common-workflow-language/user_guide/pull/226 Also, "nubs" and "To Dos" have been placed as comments in the User Guide itself to let you know where things might be added.

v1.1, v1.2 Features

• [ ] Mention version mixing; and explain when and how to use cwl-upgrader, https://github.com/common-workflow-language/user_guide/issues/188
• [ ] NetworkAccess: Need example to show how to Indicate whether a process requires outgoing IPv4/IPv6 network access and what happens if not indicated and ]network access is need but isn't available, https://github.com/common-workflow-language/user_guide/issues/249

Expanding/Revising Existing Content

In Introduction/Prerequisite

• [ ] Include where the cwl-runner source is? Note from Bruno when writing this section - "I couldn't find in PYPI ait points to the CWL project: https://github.com/common-workflow-language/cwltool/tree/main/cwlref-runner", NO CURRENT TICKET FOR THIS , but has a note in the markdown as a TODO

In Introduction/Basic Concepts

• [ ] Add a link to the Core Concepts -> Requirements section, NO CURRENT TICKET - but has a note in the markdown as a TODO

In Topics/CommandLineTool

• [ ] Spaces in commands , https://github.com/common-workflow-language/user_guide/issues/39
• [ ] Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs), No existing ticket just a common bottom of the markdown

In Topics/ExpressionTool

• [ ] Explain better with more examples (need to get more information for this)

In Topics/Inputs

• [ ] Explain its fields, such as default, valueFrom, etc., https://github.com/common-workflow-language/common-workflow-language/issues/359
• [ ] Exclusive parameters, https://github.com/common-workflow-language/user_guide/issues/162 Maybe fixed by waiting pull request
• [ ] Optional Inputs, https://github.com/common-workflow-language/user_guide/issues/44
• [ ] Several ways of defining inputs/arguments to tools and workflows, https://github.com/common-workflow-languag/user_guide/issues/33
• [ ] Using an input output in another input, https://github.com/common-workflow-language/user_guide/issues/90
• [ ] How to use linkMerge, https://github.com/common-workflow-language/user_guide/issues/117 (or maybe move to Advanced?)
• [ ] Secondary files, https://github.com/common-workflow-language/common-workflow-language/issues/270

Location-TBD

• [ ] Improve Scatter documentation, https://github.com/common-workflow-language/user_guide/issues/232.
• [ ] Expand Section on Containers to include Singularity, https://github.com/common-workflow-language/user_guide/issues/231
• [ ] Running cwltool in a container, https://github.com/common-workflow-language/user_guide/issues/231
• [ ] Update and clarify existing docker example, https://github.com/common-workflow-language/user_guide/issues/231 and https://github.com/common-workflow-language/user_guide/issues/119 , https://github.com/common-workflow-language/user_guide/issues/190
• [ ] Explain about running cwltool inside docker containers, https://github.com/common-workflow-language/user_guide/issues/231
• [ ] Make a better example for showing metadata instead of running wordcount on a bam file, https://github.com/common-workflow-language/user_guide/issues/190
• [ ] Add content for mutually exclusive inputs, https://github.com/common-workflow-language/user_guide/issues/229
• [ ] Show how to extract a specific element from an array, https://github.com/common-workflow-language/user_guide/issues/184
• [ ] Explain multi-dimensional scattering and give an example, https://github.com/common-workflow-language/user_guide/issues/181
• [ ] Highlight the major features of cwltool (e.g. --validate, --parallel ), Note: Some of this has been done but some left to do. , https://github.com/common-workflow-language/user_guide/issues/166
• [ ] Explain Shell Command - https://github.com/common-workflow-language/user_guide/issues/159 Looks like it should so in the nub of the "4.12. Requirements and Hints"
• [ ] Explain how to reference a local script, https://github.com/common-workflow-language/user_guide/issues/158 Note: this doesn't have placement in the new structure - so maybe FAQs?

Formatting Issues

• [ ] Table of Contents doesn't show important workflow subsections, https://github.com/common-workflow-language/user_guide/issues/252
• [ ] Extra box on left-hand-side table of contents, https://github.com/common-workflow-language/user_guide/issues/244
• [ ] Adjust wording to use Topics instead of Core Concepts in Intro - https://github.com/common-workflow-language/user_guide/issues/255

Needs Clarification or More Information

• [ ] Explain drawback with docker, https://github.com/common-workflow-language/user_guide/issues/239 - Some of this is already explained. in User Guide but not the singularity/docker interaction.
• [ ] Guidelines or Best Practices for the scope of command line tools. , https://github.com/common-workflow-language/user_guide/issues
• [ ] Example for using expressions with exclusive parameter (an example has to be made for this issue), https://github.com/common-workflow-language/user_guide/issues
• [ ] Need to explain how to add conformance tests and/or add them for new example, https://github.com/common-workflow-language/user_guide/issues/254
• [ ] - [ ] Fix the missing link the graph below (CWL command-line tool.) We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: command-line-tool-graph, NO CURRENT TICKET FOR THIS, but it has a note in the markdown as a TODO
• [ ] Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html).:name: echo.cwl, No current ticket for this, but it has a note in the markdown as a TODO
• [ ] Fix the missing link the graph below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html). :name: expression-tool-graph, NO CURRENT TICKET, but it has note in the markdown as a TODO
• [ ] Fix the missing link the code below. We cannot have it here as this file is included in two other files. Sphinx prohibits it for the case where this could lead to duplicate anchors in a page (e.g. single-html).:name: uppercase.cwl

May Be Fixed by Outstanding Pull Requests

• [ ] Show how to transpile newer Javascript code for ECMAScript 5.1, https://github.com/common-workflow-language/user_guide/issues/245

[swzCuroverse]

I am working on making this master list of tickets. if you are heading to this ticket from Outreachy - the list of open tickets above is not complete. I should have it finished by October 11th 2022. I am trying to also add new tickets as they come to make it a bit of a "living" ticket to help us keep track of what we still need to do.

To clarify and confusion, I just working am working on cleaning up and organizing the tickets. The work described in the tickets themselves are open and available for anyone to work on.

[smyja]

I am working on this - but if you are heading to this ticket from Outreachy - all the above is up to date, it is just not complete. I should have it finished by October 11th 2022. I am trying to also add new tickets as they come to make it a bit of a "living" ticket to help us keep track of where in the User Guide these new issues fit in.

Hey, do you mean you are already resolving every issue or you mean you are still updating the list of issues.

[swzCuroverse]

No, I not doing these. This is just meant to be a issue of all issues that need to be done. I am just taking ownership of moving all the known to-do to this ticket. I wouldn't mind help on that if someone wanted to help on that as well. I will change my comment above to make it clearer.

[smyja]

No, I not doing these. This is just meant to be a issue of all issues that need to be done. I am just taking ownership of moving all the known to-do to this ticket. I wouldn't mind help on that if someone wanted to help on that as well. I will change my comment above to make it clearer.

Okay. Some issues aren't listed here, like the one I raised and was merged. Also the pygments/code highlighting issue isn't here. Should I leave it? I have already started working on it though.

[Fienne]

@swzCuroverse , the issues about fixing missing links under the command line isn't really clear to me. I don't understand where to find and replace the correct links. Can you please help me out?

[swzCuroverse]

@Fienne I would skip those for now. I need to get more information about that. There is something that @kinow indicated in the read-me about an issue with graphs. I will dig into that a bit more - probably easier for you to look into one of the issues that has a ticket already written. I moved them into the Need More Information section to indicate that so other people don't run into the same problem.

[Fienne]

Alright then. Thank you.

[Timonwa]

Good day @swzCuroverse. is this a list of potential issues that outreach applicants would tackle? Can I pick a few from here and solve them?

[AfiMaameDufie]

Hi @swzCuroverse ,which issue can I pick up to work on?

[ghost]

Hello @swzCuroverse . My name is Emenyi Nelly and I am an Outreachy intern for the current session. Please can an issue be assigned to me to work on, as I am very much interested in documentation.

[paulinebanye]

Hi @swzCuroverse I'm Pauline, an outreachy intern. I'm excited to work on this project. Where do I start?

[swzCuroverse]

Hi all - please pick any ticket you find interesting above or in the general list of tickets. You ca join us on the Matrix channel here if you want guidance in setting up. https://app.element.io/#/room/#docs-training:matrix.org See the contribution guide to get started .

[chrilona]

Hello everyone,Christabel Lona Atieno just joining to learn and grow from this interaction.

[DBAKITA]

Hello @swzCuroverse in reference to the command line tool topic

Topics/CommandLineTool

Spaces in commands , https://github.com/common-workflow-language/user_guide/issues/39 Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs), No existing ticket just a common bottom of the markdown

Here is my input: How do commandlines work A Command Line Tool is a non-interactive executable program that reads some input, performs a computation, and terminates after producing some output. Command line programs are a flexible unit of code sharing and reuse, unfortunately the syntax and input/output semantics among command line programs is extremely heterogeneous. A common layer for describing the syntax and semantics of programs can reduce this incidental complexity by providing a consistent way to connect programs together. This specification defines the Common Workflow Language (CWL) Command Line Tool Description, a vendor-neutral standard for describing the syntax and input/output semantics of command line programs.

Different use cases for arguments and inputs Available primitive types are string, int, long, float, double, and null; complex types are array and record; in addition there are special types File, Directory and Any.

The following example demonstrates some input parameters with different types and appearing on the command line in different ways.

First, create a file called inp.cwl, containing the following:

inp.cwl #!/usr/bin/env cwl-runner

cwlVersion: v1.0 class: CommandLineTool baseCommand: echo inputs: example_flag: type: boolean inputBinding: position: 1 prefix: -f example_string: type: string inputBinding: position: 3 prefix: --example-string example_int: type: int inputBinding: position: 2 prefix: -i separate: false example_file: type: File? inputBinding: prefix: --file= separate: false position: 4

outputs: []

Sometimes tools require additional command line options that don’t correspond exactly to input parameters.

In this example, we will wrap the Java compiler to compile a java source file to a class file. By default, “javac” will create the class files in the same directory as the source file. However, CWL input files (and the directories in which they appear) may be read-only, so we need to instruct “javac” to write the class file to the designated output directory instead.

arguments.cwl #!/usr/bin/env cwl-runner

cwlVersion: v1.0 class: CommandLineTool label: Example trivial wrapper for Java 9 compiler hints: DockerRequirement: dockerPull: openjdk:9.0.1-11-slim baseCommand: javac arguments: ["-d", $(runtime.outdir)] inputs: src: type: File inputBinding: position: 1 outputs: classfile: type: File outputBinding: glob: "*.class"