Documentation for issue #356

openSUSE · Mar 7, 2024 · 0c8254b · 0c8254b
1 parent f8d01b7
commit 0c8254b
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 31 deletions.
diff --git a/doc/xml/daps_user_edit.xml b/doc/xml/daps_user_edit.xml
@@ -327,31 +327,34 @@ The ID "sec.template.examples.images" appears in:
 
  <para> See
    <xref linkend="ex.daps.output.default"/> and
-   <xref linkend="ex.daps.output.pretty"/> for a comparison of both outputs.</para>
+   <xref linkend="ex.daps.output.single"/> for a comparison of both outputs.</para>
 
   <example id="ex.daps.output.default">
    <title>Default output of a file listing &dapsacr; command</title>
-   <screen><?dbsuse-fo font-size="0.70em"?>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles</command>
-<replaceable>YOUR_PRJ_DIR</replaceable>/DC-daps-example&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example1.png&nbsp;<replaceable
->YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
-  </example>
-
-  <example id="ex.daps.output.pretty">
-   <title>Pretty-printed output of a file listing &dapsacr; command</title>
-   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--pretty</command>
+   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles</command>
 <replaceable>YOUR_PRJ_DIR</replaceable>/DC-daps-example
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png1.png
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png
 <replaceable>YOUR_PRJ_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
   </example>
 
+  <example id="ex.daps.output.single">
+   <title>Single line output of a file listing &dapsacr; command</title>
+   <screen><?dbsuse-fo font-size="0.70em"?>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles | xargs</command>
+<replaceable>YOUR_PRJ_DIR</replaceable>/DC-daps-example&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example1.png&nbsp;<replaceable
+>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
+   <screen><?dbsuse-fo font-size="0.70em"?>&prompt.user;<command>echo $(daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles)</command>
+<replaceable>YOUR_PRJ_DIR</replaceable>/DC-daps-example&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example1.png&nbsp;<replaceable
+>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png&nbsp;<replaceable>YOUR_PRJ_DIR</replaceable>/xml/MAIN-daps-example.xml</screen>
+  </example>
+
   <tip>
    <title>Using pretty-printed output for counting</title>
    <para>To count the number of files listed in a given output, you can
-    also combine the <parameter>--pretty</parameter> parameter with the
+    use the <parameter>--pretty</parameter> parameter and pipe the output to the
     <command>wc</command> command: </para>
    <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles --pretty | wc -l</screen>
-   <para> For <xref linkend="ex.daps.output.pretty"
+   <para> For <xref linkend="ex.daps.output.default"
    xrefstyle="select:label"/>, the command above would return
     <literal>4</literal> as a value.
    </para>

diff --git a/doc/xml/daps_user_images.xml b/doc/xml/daps_user_images.xml
@@ -282,7 +282,7 @@
     <term>Listing All Graphics Referenced in a Documentation Project
      </term>
     <listitem>
-     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--noent&nbsp;--noxml&nbsp;--nodc</screen>
+     <screen>&prompt.user;&dapscmd;&nbsp;<parameter>-d</parameter>&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--imgonly</screen>
      <para> Lists all graphics file used by the DocBook files that are referenced in the document
       specified by the current &dc; file. </para>
     </listitem>
@@ -362,30 +362,34 @@
 
   <para> See
    <xref linkend="ex.daps.graphics.output.default"/> and
-   <xref linkend="ex.daps.graphics.output.pretty"/> for a comparison of both outputs.</para>
+   <xref linkend="ex.daps.graphics.output.single"/> for a comparison of both outputs.</para>
 
   <example id="ex.daps.graphics.output.default">
-   <title>Default Output of an Image-related &dapsacr; Command</title>
-   <screen><?dbsuse-fo font-size="0.70em"?><replaceable>YOUR_PRJ_DIR</replaceable>/images/src/dia/example_dia1.dia <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png1.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png3.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/svg/example_svg.svg ...</screen>
-  </example>
-
-  <example id="ex.daps.graphics.output.pretty">
-   <title>Pretty-printed Output of an Image-related &dapsacr;
-    Command</title>
-   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-images-multisrc&nbsp;--pretty</command>
+    <title>Default output of an image-related &dapsacr; command</title>
+    <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfilesc&nbsp;--imgonly</command>
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/dia/example_dia1.dia
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png1.png
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png
 <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png3.png
-<replaceable>YOUR_PRJ_DIR</replaceable>/images/src/svg/example_svg.svg ...</screen>
+<replaceable>YOUR_PRJ_DIR</replaceable>/images/src/svg/example_svg.svg</screen>
+  </example>
+
+  <example id="ex.daps.graphics.output.single">
+   <title>Single line output of an image-related &dapsacr;
+    command</title>
+   <screen>&prompt.user;<command>daps -d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--imgonly | xargs</command>
+   <?dbsuse-fo font-size="0.70em"?><replaceable>YOUR_PRJ_DIR</replaceable>/images/src/dia/example_dia1.dia <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png1.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png3.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/svg/example_svg.svg</screen>
+   <screen>&prompt.user;<command>echo $(daps-d&nbsp;<replaceable>PATH_TO_&dc;_FILE</replaceable>&nbsp;list-srcfiles&nbsp;--imgonly)</command>
+   <?dbsuse-fo font-size="0.70em"?><replaceable>YOUR_PRJ_DIR</replaceable>/images/src/dia/example_dia1.dia <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png1.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png2.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/png/example_png3.png <replaceable>YOUR_PRJ_DIR</replaceable>/images/src/svg/example_svg.svg</screen>
   </example>
 
   <tip>
    <title>Use Pretty-Printed Output for Counting</title>
-   <para> To count the number of images listed in a given output, you can combine the <parameter>--pretty</parameter> parameter with the
+   <para> To count the number of images listed in a given output, you can use
+   the <parameter>--pretty</parameter> parameter and pipe the output to the
     <command>wc</command> command: </para>
-   <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> list-images-multisrc --pretty | wc -l</screen>
-   <para> For <xref linkend="ex.daps.graphics.output.pretty"
+   <screen>&prompt.user;&dapscmd; -d <replaceable>PATH_TO_&dc;_FILE</replaceable> list-srcfiles --imgonly --pretty | wc -l</screen>
+   <para> For <xref linkend="ex.daps.graphics.output.default"
     xrefstyle="select:label"/>, the command above would return
     <computeroutput>5</computeroutput> as value.
    </para>

diff --git a/doc/xml/phrases-decl.ent b/doc/xml/phrases-decl.ent
@@ -791,12 +791,11 @@ directory and in the profiled sources, as indicated by
 <!ENTITY daps-note-filelists
 ' <note>
    <title>Output of file listings</title>
-   <para>By default, the output of the listing commands is a list of file names
-    (including the absolute path), all printed in one line with the file names
-    separated by blanks. This default output format is useful for piping (or
-    copying and pasting) the output for use with another command. </para>
-   <para>If you need a pretty-printed output where each file name is listed on a
-    separate line, use the <option>--pretty</option> option. </para>
+   <para>By default, the output of the listing commands is a list of single file
+    names on separate lines. In case the output does not go to the
+    terminal (e.g. when being passed to a pipe) all names are printed on a single
+    line with the file names separated by spaces (unless you use the
+    <option>--pretty</option> parameter). </para>
   </note>'>
 
 <!ENTITY daps-note-superfluous-files