doc: fix PDF build of bbdev prog guide
PATCH 1/1 doc: fix PDF build of bbdev prog guide
Some machine (like on dpdk.org) may fail to build the prog guide PDF because of the complex table inserted in the bbdev chapter.
--- doc/guides/prog_guide/bbdev.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-)
doc/guides/prog_guide/bbdev.rst +16 -16
@@ -800,21 +800,21 @@ The LDPC encode parameters are set out in the table below. |op_flags |bitmask of all active operation capabilities | +----------------+--------------------------------------------------------------------+ |**cb_params** |code block specific parameters (code block mode only) | -+----------------+------------+-------------------------------------------------------+ -| |e |E, length of the rate matched output sequence in bits | -+----------------+------------+-------------------------------------------------------+ ++----------------+--------------------------------------------------------------------+ +|e |E, length of the rate matched output sequence in bits | ++----------------+--------------------------------------------------------------------+ |**tb_params** | transport block specific parameters (transport block mode only) | -+----------------+------------+-------------------------------------------------------+ -| |c |number of CBs in the TB or partial TB | -+----------------+------------+-------------------------------------------------------+ -| |r |index of the first CB in the inbound mbuf data | -+----------------+------------+-------------------------------------------------------+ -+ +c_ab +number of CBs that use Ea before switching to Eb | -+----------------+------------+-------------------------------------------------------+ -| |ea |Ea, length of the RM output sequence in bits, r < cab | -+----------------+------------+-------------------------------------------------------+ -| |eb |Eb, length of the RM output sequence in bits, r >= cab | -+----------------+------------+-------------------------------------------------------+ ++----------------+--------------------------------------------------------------------+ +|c |number of CBs in the TB or partial TB | ++----------------+--------------------------------------------------------------------+ +|r |index of the first CB in the inbound mbuf data | ++----------------+--------------------------------------------------------------------+ ++c_ab +number of CBs that use Ea before switching to Eb | ++----------------+--------------------------------------------------------------------+ +|ea |Ea, length of the RM output sequence in bits, r < cab | ++----------------+--------------------------------------------------------------------+ +|eb |Eb, length of the RM output sequence in bits, r >= cab | ++----------------+--------------------------------------------------------------------+ The mbuf input ``input`` is mandatory for all BBDEV PMDs and is the incoming code block or transport block data.
@@ -865,7 +865,7 @@ calculated by BBDEV before signalling to the driver. The number of CBs in the group should not be confused with ``c``, the total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) -Figure 13.1 above showing the Turbo encoding of CBs using BBDEV +Figure :numref:`figure_turbo_tb_encode` above showing the Turbo encoding of CBs using BBDEV interface in TB-mode is also valid for LDPC encode. BBDEV LDPC Decode Operation
@@ -1077,7 +1077,7 @@ total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in case they were appended by the application. -Figure 13.2 above showing the Turbo decoding of CBs using BBDEV +Figure :numref:`figure_turbo_tb_decode` above showing the Turbo decoding of CBs using BBDEV interface in TB-mode is also valid for LDPC decode.
Signature · 1 line
1.8.3.1
18/07/2019 08:24, Nicolas Chautru:
Quoted 3 lines
doc/guides/prog_guide/bbdev.rst +1
-1-Figure 13.1 above showing the Turbo encoding of CBs using BBDEV +Figure :numref:`figure_turbo_tb_encode` above showing the Turbo encoding of CBs using BBDEV interface in TB-mode is also valid for LDPC encode.
[...]
doc/guides/prog_guide/bbdev.rst total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) · line 1081
Quoted 3 lines
doc/guides/prog_guide/bbdev.rst +1
-1-Figure 13.2 above showing the Turbo decoding of CBs using BBDEV +Figure :numref:`figure_turbo_tb_decode` above showing the Turbo decoding of CBs using BBDEV interface in TB-mode is also valid for LDPC decode.
3 comments above the change of references:
- there are a lot more, please search for the word "section"
- it deserves a separate commit
- the line length should be below 100 chars, better below 80. The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc.
Example:
Figure :numref:figure_turbo_tb_encode above
showing the Turbo encoding of CBs using BBDEV interface in TB-mode is also valid for LDPC encode.
From: Thomas Monjalon [mailto:[email protected]]
Quoted 3 lines
3 comments above the change of references:
- there are a lot more, please search for the word "section"
All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents.
Quoted 1 line
- it deserves a separate commit
OK. And you want such a commit now for 19.09 or later on?
Quoted 6 lines
- the line length should be below 100 chars, better below 80.
The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc. Example:
Figure :numref:figure_turbo_tb_encodeabove
showing the Turbo encoding of CBs using BBDEV interface in TB-mode
is also valid for LDPC encode.
All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later.
18/07/2019 16:43, Chautru, Nicolas:
Quoted 6 lines
From: Thomas Monjalon [mailto:[email protected]]
Quoted 3 lines
3 comments above the change of references:
- there are a lot more, please search for the word "section"
All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents.
You're right! I completely overlooked it.
Quoted 3 lines
Quoted 1 line
- it deserves a separate commit
OK. And you want such a commit now for 19.09 or later on?
Given there are only 2 figure refs, it can stay with PDF fix.
Quoted 8 lines
Quoted 6 lines
- the line length should be below 100 chars, better below 80.
The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc. Example:
Figure :numref:figure_turbo_tb_encodeabove
showing the Turbo encoding of CBs using BBDEV interface in TB-mode
is also valid for LDPC encode.All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later.
The rule is to not do cosmetic change :)
I was explaining the line breaking for the lines you were changing while fixing figure ref.
I think I will apply this patch and adjust the line breaking if needed. Is it OK?
From: Thomas Monjalon [mailto:[email protected]]
Quoted 23 lines
18/07/2019 16:43, Chautru, Nicolas:
Quoted 6 lines
From: Thomas Monjalon [mailto:[email protected]]
Quoted 3 lines
3 comments above the change of references:
- there are a lot more, please search for the word "section"
All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents.
You're right! I completely overlooked it.
Quoted 3 lines
Quoted 1 line
- it deserves a separate commit
OK. And you want such a commit now for 19.09 or later on?
Given there are only 2 figure refs, it can stay with PDF fix.
Quoted 7 lines
Quoted 6 lines
- the line length should be below 100 chars, better below 80.
The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc. Example:
Figure :numref:figure_turbo_tb_encodeabove
showing the Turbo encoding of CBs using BBDEV interface in TB-mode
is also valid for LDPC encode.
Quoted 7 lines
Quoted 1 line
All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later.
The rule is to not do cosmetic change :) I was explaining the line breaking for the lines you were changing while fixing figure ref.
I think I will apply this patch and adjust the line breaking if needed. Is it OK?
Ok with me. Thanks Thomas.
18/07/2019 08:24, Nicolas Chautru:
Quoted 5 lines
Some machine (like on dpdk.org) may fail to build the prog guide PDF because of the complex table inserted in the bbdev chapter.
Fixes 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")Signed-off-by Nicolas Chautru <[email protected]>
Thanks for the quick reaction.
If you agree, I can apply this patch without the changes of figure refs.
About the tables, there are simpler syntax in RsT:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
You can also consider the definition lists:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists
From: Thomas Monjalon [mailto:[email protected]]
Quoted 9 lines
18/07/2019 08:24, Nicolas Chautru:
Quoted 5 lines
Some machine (like on dpdk.org) may fail to build the prog guide PDF because of the complex table inserted in the bbdev chapter.
Fixes 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")Signed-off-by Nicolas Chautru <[email protected]>Thanks for the quick reaction.
If you agree, I can apply this patch without the changes of figure refs.
No problem, we can fix the other cosmetic changes that you have raised post 19.09.
Quoted 2 lines
About the tables, there are simpler syntax in RsT:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
To be honest, I cannot see the problem with the current format which is following that structure already. What error message do you get on your machine? This is not caught on DPDK CI, is it?
Quoted 2 lines
You can also consider the definition lists:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists
Clearer has a formal table from my point of view.
Thanks
18/07/2019 16:51, Chautru, Nicolas:
Quoted 5 lines
From: Thomas Monjalon [mailto:[email protected]]
Quoted 2 lines
About the tables, there are simpler syntax in RsT:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tablesTo be honest, I cannot see the problem with the current format which is following that structure already.
You are using the grid table syntax.
I was referring to the simple table syntax as below:
===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ======
Quoted 1 line
What error message do you get on your machine?
That's the difficult thing with PDF build, we do not have any clear error message. I had to bisect to find the root cause.
Quoted 1 line
This is not caught on DPDK CI, is it?
No and I cannot reproduce it on my laptop.
I see the failure only on dpdk.org which has a different OS version.
Quoted 4 lines
Quoted 2 lines
You can also consider the definition lists:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-listsClearer has a formal table from my point of view.
Yes maybe, it depends on what we want to document.
18/07/2019 08:24, Nicolas Chautru:
Quoted 12 lines
Some machine (like on dpdk.org) may fail to build the prog guide PDF because of the complex table inserted in the bbdev chapter.
Fixes 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")Signed-off-by Nicolas Chautru <[email protected]>---
doc/guides/prog_guide/bbdev.rst +0
-4-+----------------+------------+-------------------------------------------------------+ -| |c |number of CBs in the TB or partial TB | -+----------------+------------+-------------------------------------------------------+ -| |r |index of the first CB in the inbound mbuf data |
doc/guides/prog_guide/bbdev.rst The LDPC encode parameters are set out in the table below. · line 813
Quoted 10 lines
doc/guides/prog_guide/bbdev.rst +7
-3-+----------------+------------+-------------------------------------------------------+ -+ +c_ab +number of CBs that use Ea before switching to Eb | -+----------------+------------+-------------------------------------------------------+ ++----------------+--------------------------------------------------------------------+ +|c |number of CBs in the TB or partial TB | ++----------------+--------------------------------------------------------------------+ +|r |index of the first CB in the inbound mbuf data | ++----------------+--------------------------------------------------------------------+ ++c_ab +number of CBs that use Ea before switching to Eb | ++----------------+--------------------------------------------------------------------+
Actually the problem is still here: the table line is "+" instead of "|". I'll fix it, keeping the original format.
PATCH v3 1/1 doc: fix PDF build of bbdev prog guide
In reply to Nicolas ChautruSome machine (like on dpdk.org) may fail to build the prog guide PDF because of a table characher being "+" instead of "|".
Some figure references are also fixed with automatic numbering.
---
v3: fix only the bad character and keep complex table (Thomas)
v2: try simpler table and fix figure refs (Nicolas)
v1: remove some table rows (Thomas)
--- doc/guides/prog_guide/bbdev.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-)
doc/guides/prog_guide/bbdev.rst +7 -5
@@ -809,7 +809,7 @@ The LDPC encode parameters are set out in the table below. +----------------+------------+-------------------------------------------------------+ | |r |index of the first CB in the inbound mbuf data | +----------------+------------+-------------------------------------------------------+ -+ +c_ab +number of CBs that use Ea before switching to Eb | +| |c_ab |number of CBs that use Ea before switching to Eb | +----------------+------------+-------------------------------------------------------+ | |ea |Ea, length of the RM output sequence in bits, r < cab | +----------------+------------+-------------------------------------------------------+
@@ -865,8 +865,9 @@ calculated by BBDEV before signalling to the driver. The number of CBs in the group should not be confused with ``c``, the total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) -Figure 13.1 above showing the Turbo encoding of CBs using BBDEV -interface in TB-mode is also valid for LDPC encode. +Figure :numref:`figure_turbo_tb_encode` above +showing the Turbo encoding of CBs using BBDEV interface in TB-mode +is also valid for LDPC encode. BBDEV LDPC Decode Operation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1077,8 +1078,9 @@ total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in case they were appended by the application. -Figure 13.2 above showing the Turbo decoding of CBs using BBDEV -interface in TB-mode is also valid for LDPC decode. +Figure :numref:`figure_turbo_tb_decode` above +showing the Turbo decoding of CBs using BBDEV interface in TB-mode +is also valid for LDPC decode. Sample code
Signature · 1 line
2.21.0
19/07/2019 00:01, Thomas Monjalon:
Quoted 7 lines
Some machine (like on dpdk.org) may fail to build the prog guide PDF because of a table characher being "+" instead of "|".
Some figure references are also fixed with automatic numbering.
Fixes 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")
Quoted 7 lines
Signed-off-by Thomas Monjalon <[email protected]>Signed-off-by Nicolas Chautru <[email protected]>---
v3: fix only the bad character and keep complex table (Thomas)
v2: try simpler table and fix figure refs (Nicolas)
v1: remove some table rows (Thomas)
---
Applied quickly