Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change cite to literal text #3866

Merged
merged 3 commits into from
Aug 28, 2023
Merged

Change cite to literal text #3866

merged 3 commits into from
Aug 28, 2023

Conversation

cychitivav
Copy link
Contributor

Add :samp role to improve copy-paste (Before, Sphinx detected the S. for Steven Macenski as a numbered list)

Before:
image

Now:
image

Copy link
Contributor

@clalancette clalancette left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice find!

The documentation for :samp: says this:

A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part,
as in [file](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file).
For example, in :samp:`print 1+{variable}`, the part variable would be emphasized: print 1+variable

If you don’t need the “variable part” indication,
use the standard [code](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-code) role instead.

:samp: and :code: seem to generate nearly identical HTML in the end. I'm on the fence about it, since using :code: is kind of weird here. Any thoughts on which way we should go?

@cychitivav
Copy link
Contributor Author

cychitivav commented Aug 28, 2023

I explored the Sphinx documentation and couldn't find a dedicated role for citations. However, while reviewing the quote blocks, I stumbled upon a workaround. By using the | symbol, we can preserve line breaks, which would prevent the abbreviation S. from being treated as a numbered list.

Quoted paragraphs (reference) can be created by indenting them more than the surrounding paragraphs.

Line blocks (reference) provide a way to maintain line breaks:

| These lines are
| broken in the same way as they appear
| in the source file.

This approach maintains the indentation that was used in the numbered list to distinguish it from regular text.
image

Postscript: I have added syntax highlighting for citations in BibTeX.

Copy link
Contributor

@clalancette clalancette left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it! Thanks for iterating there.

I've left one more minor set of changes (to switch to ASCII quotes, which we use almost everywhere else), and then I'm happy with this.

source/Citations.rst Outdated Show resolved Hide resolved
source/Citations.rst Outdated Show resolved Hide resolved
@clalancette clalancette added the backport-all backport at reviewers discretion; from rolling to all versions label Aug 28, 2023
Co-authored-by: Chris Lalancette <clalancette@gmail.com>
Copy link
Contributor

@clalancette clalancette left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this looks good now. I'll go ahead and merge it.

@clalancette clalancette merged commit a361bcd into ros2:rolling Aug 28, 2023
3 checks passed
mergify bot pushed a commit that referenced this pull request Aug 28, 2023
* Change cite to literal text

* Add bibtex syntax highlight and blockquote with line break preservation

* Switch left and right quotes to ASCII quotes
Co-authored-by: Chris Lalancette <clalancette@gmail.com>

(cherry picked from commit a361bcd)
mergify bot pushed a commit that referenced this pull request Aug 28, 2023
* Change cite to literal text

* Add bibtex syntax highlight and blockquote with line break preservation

* Switch left and right quotes to ASCII quotes
Co-authored-by: Chris Lalancette <clalancette@gmail.com>

(cherry picked from commit a361bcd)
clalancette pushed a commit that referenced this pull request Aug 28, 2023
* Change cite to literal text

* Add bibtex syntax highlight and blockquote with line break preservation

* Switch left and right quotes to ASCII quotes
Co-authored-by: Chris Lalancette <clalancette@gmail.com>

(cherry picked from commit a361bcd)

Co-authored-by: Cristian Chitiva <cychitivav@unal.edu.co>
clalancette pushed a commit that referenced this pull request Aug 28, 2023
* Change cite to literal text

* Add bibtex syntax highlight and blockquote with line break preservation

* Switch left and right quotes to ASCII quotes
Co-authored-by: Chris Lalancette <clalancette@gmail.com>

(cherry picked from commit a361bcd)

Co-authored-by: Cristian Chitiva <cychitivav@unal.edu.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
backport-all backport at reviewers discretion; from rolling to all versions
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants