Probably just before the Conclusion section, or perhaps (at the risk of some repetitive text) in the links section for icons specifically, since I think that's how they're most used. Very rough draft language: > To insert an icon (small picture) as a shorthand symbol for text (for instance, an envelope in a mailto: link), use: > > icon:filename_without_extension[Text description, link=https://host.example.org/some/URL] > > To insert an image, use: > > image::filename.extension[alt="Text description"] Images are described in the Rosetta Stone chapter, but icons aren't. I'd want both in the same place, but I'm not sure where (or if, in a latter step, these chapters should get merged). For extra credit, I'd add "always use meaningful image and icon descriptions" or words to that effect to the style guide.
(In reply to PauAmma from comment #0) dbaio just pointed out to me that the FDP uses font icons, not image icons, so the above applies only to images, not icons.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=2cfe75b557140446dfdfd081d87f9a4ac6f2880b commit 2cfe75b557140446dfdfd081d87f9a4ac6f2880b Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2023-09-20 07:38:41 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2023-09-20 07:38:41 +0000 FDP: Add subsection about images and icons PR: 261847 Reviewed by: bcr@ Differential Revision: https://reviews.freebsd.org/D41775 .../fdp-primer/asciidoctor-primer/_index.adoc | 83 ++++++++++++++++++++++ 1 file changed, 83 insertions(+)
Done.