On Mon, 20 Sep 2021, Akira Yokosawa <akiyks@xxxxxxxxx> wrote:
> Nested grids in grid-table cells are not specified as proper ReST
> constructs.
> Commit 572f2a5cd974 ("drm/i915/guc: Update firmware to v62.0.0")
> added a couple of kerneldoc tables of the form:
>
> +---+-------+------------------------------------------------------+
> | 1 | 31:0 | +------------------------------------------------+ |
> +---+-------+ | | |
> |...| | | Embedded `HXG Message`_ | |
> +---+-------+ | | |
> | n | 31:0 | +------------------------------------------------+ |
> +---+-------+------------------------------------------------------+
>
> For "make htmldocs", they happen to work as one might expect,
> but they are incompatible with "make latexdocs" and "make pdfdocs",
> and cause the generated gpu.tex file to become incomplete and
> unbuildable by xelatex.
>
> Restore the compatibility by removing those nested grids in the tables.
>
> Size comparison of generated gpu.tex:
>
> Sphinx 2.4.4 Sphinx 4.2.0
> v5.14: 3238686 3841631
> v5.15-rc1: 376270 432729
> with this fix: 3377846 3998095
>
> Fixes: 572f2a5cd974 ("drm/i915/guc: Update firmware to v62.0.0")
> Cc: John Harrison <John.C.Harrison@xxxxxxxxx>
> Cc: Michal Wajdeczko <michal.wajdeczko@xxxxxxxxx>
> Cc: Matthew Brost <matthew.brost@xxxxxxxxx>
> Cc: Daniele Ceraolo Spurio <daniele.ceraolospurio@xxxxxxxxx>
> Cc: Matt Roper <matthew.d.roper@xxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> ---
> Hi all,
>
> I know there is little interest in building pdfdocs (or LaTeX) version
> of kernel-doc, and this issue does not matter most of you.
>
> But "make pdfdocs" is supposed to work, give or take those tables
> with squeezed columns, and at least it is expected to complete
> without fatal errors.
Absolutely!
> I have no idea who is responsible to those grid-tables, so added
> a lot of people in the To: and Cc: lists.
>
> Does removing those nested grids look reasonable to you?
>
> Any feedback is welcome!
>
> Note: This patch is against the docs-next branch of Jon's -doc tree
> (git://git.lwn.net/linux.git). It can be applied against v5.15-rc1
> and v5.15-rc2 as well.
I think this should go through drm-intel, and it'll find its way back to
some v5.15-rc.
BR,
Jani.
>
> Thanks, Akira
> --
> .../gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h | 10 +++++-----
> .../drm/i915/gt/uc/abi/guc_communication_mmio_abi.h | 10 +++++-----
> 2 files changed, 10 insertions(+), 10 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h
> index 99e1fad5ca20..c9086a600bce 100644
> --- a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h
> +++ b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h
> @@ -102,11 +102,11 @@ static_assert(sizeof(struct guc_ct_buffer_desc) == 64);
> * | +-------+--------------------------------------------------------------+
> * | | 7:0 | NUM_DWORDS = length (in dwords) of the embedded HXG message |
> * +---+-------+--------------------------------------------------------------+
> - * | 1 | 31:0 | +--------------------------------------------------------+ |
> - * +---+-------+ | | |
> - * |...| | | Embedded `HXG Message`_ | |
> - * +---+-------+ | | |
> - * | n | 31:0 | +--------------------------------------------------------+ |
> + * | 1 | 31:0 | |
> + * +---+-------+ |
> + * |...| | [Embedded `HXG Message`_] |
> + * +---+-------+ |
> + * | n | 31:0 | |
> * +---+-------+--------------------------------------------------------------+
> */
>
> diff --git a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h
> index bbf1ddb77434..9baa3cb07d13 100644
> --- a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h
> +++ b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h
> @@ -38,11 +38,11 @@
> * +---+-------+--------------------------------------------------------------+
> * | | Bits | Description |
> * +===+=======+==============================================================+
> - * | 0 | 31:0 | +--------------------------------------------------------+ |
> - * +---+-------+ | | |
> - * |...| | | Embedded `HXG Message`_ | |
> - * +---+-------+ | | |
> - * | n | 31:0 | +--------------------------------------------------------+ |
> + * | 0 | 31:0 | |
> + * +---+-------+ |
> + * |...| | [Embedded `HXG Message`_] |
> + * +---+-------+ |
> + * | n | 31:0 | |
> * +---+-------+--------------------------------------------------------------+
> */
>
>
> base-commit: 242f4c77b1c8cebfdfa0ad5b40e2e4ae0316e57d
--
Jani Nikula, Intel Open Source Graphics Center
