Remove punctuation mark from the figure captions #1444
Conversation
|
I assume, images captions also have to be updated by removing trailing dot. |
Didn't get. Are you talking about removing punctuation mark from here? I was thinking about removing these punctuation marks, also, but in a separate commit. At some place, it doesn't end with punctuation mark (like this), and at some places it does. |
|
There is one more issue, due to this PR, some paragraph don't have any punctuation mark (see below) because those punctuation mark are their because of caption.
I think a separate commit would be good idea because I found there are also other places where punctuation marks are missing like this which have nothing to do with this PR. |
etanot
changed the title
Removing punctuation marks from caption text (text in square bracket) don't fix the problem (see below and this also),
but removing it from text present above
I've tested this before pull request and now I confirm it. Anyway I'm making changes that you've suggested, once it completed I'll force push it. Edit:
|
|
Some figures don't have any caption associated with them, like in rerere.asc, reset.asc and replace.asc; and if you scroll below, you'll notice none of figure have any captions associated with them. Should I assign some caption to those figure? Or leave as it's. |
Yes, you were right. For "block" image AsciiDoc uses its title form line above that starts from dot to create a signature like "Figure N: Image title". Additionally, the same text from the image block is used to create a link to image if it's mentioned in the text. The title in brackets is using only for popup tip, but for "block" images it's not working (at least in html, epub and pdf versions of book and example at https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images)
I don't know will this issue be fixed later in AsciiDoc or do we need to remove those captions from brackets if they are. As for now, I recommend you to leave them as-is.
IMHO, it's a good idea to add a meaningful caption to images that have no it. |
If a paragraph ends with a figure caption, it ends with double period marks. One of them is due to figure caption, which itself ends with a period and other is for end of paragraph. So removing period from figure captions would be a good idea, as Ben has suggested[1]. Due to this commit, now some paragraphs don't have any period mark at end of paragraph. Those period are their because of caption, that's paragraphs itself don't end with any period, see [2]. [1]: progit#1437 (comment) [2]: progit#1444 (comment) Resolves: progit#1437
- After removing period mark from figure captions; some paragraph left with no period because those paragraph has only one period and that's because of figure caption (see progit#1444 (comment)). - End all bullet points with a period.
etanot
changed the title
|
@Morganov I've made all changes that you've suggested. Can you review it, now? |
Sorry, I've already put same text as in caption in empty square bracket. At most places same text has been used in square bracket. If you want to discard those changes, you can discard it; I've put these changes in a separate commit.
May be I'll do it in separate PR. |
| * What the project is for | ||
| * How to configure and install it | ||
| * An example of how to use it or get it running | ||
| * The license that the project is offered under | ||
| * How to contribute to it | ||
| * What the project is for. | ||
| * How to configure and install it. | ||
| * An example of how to use it or get it running. | ||
| * The license that the project is offered under. | ||
| * How to contribute to it. |
There was a problem hiding this comment.
I'd say leave the periods off of these. It's a bullet list of sentence fragments.
There was a problem hiding this comment.
Actually, I follow Garner's book for punctuation, in which it's stated that if bullet point starts with a lowercase letter, end it with semicolon except last one which ends with period. And if bullet starts with uppercase letter end it with period; and by convention a fragment would be acceptable units. Let me check it for APA style.
There was a problem hiding this comment.
Okay, in APA style we may not use punctuation with fragments of sentence; but my question is, are these statements really fragments of a sentence or a complete sentence? These statements can exist alone; and also if we're assuming these statements as fragments, it should start with lowercase.
| * The name of the reference being pushed to | ||
| * The old revision where that branch was | ||
| * The new revision being pushed | ||
| * The name of the reference being pushed to. | ||
| * The old revision where that branch was. | ||
| * The new revision being pushed. |
There was a problem hiding this comment.
Again, bullet lists don't need punctuation.
| * git push origin :branch-to-delete (Bazaar can't accept ref deletions in this way.) | ||
| * git push origin old:new (it will push 'old') | ||
| * git push --dry-run origin branch (it will push) | ||
| * git push origin :branch-to-delete (Bazaar can't accept ref deletions in this way). | ||
| * git push origin old:new (it will push 'old'). | ||
| * git push --dry-run origin branch (it will push). |
There was a problem hiding this comment.
Bullet lists don't need punctuation.
There was a problem hiding this comment.
How about this?
* `git push origin :branch-to-delete`: Bazaar can't accept ref deletions in this way,
* `git push origin old:new`: it will push 'old',
* `git push --dry-run origin branch`: it will push.
git push origin :branch-to-delete: Bazaar can't accept ref deletions in this way,git push origin old:new: it will push 'old',git push --dry-run origin branch: it will push.
see APA style section 6.52 (Items That Contain Both Phrases and Sentences).
There was a problem hiding this comment.
I don't think that it's the best way to use the in-line comment for the command example.
The colon symbol is used in Git as a special symbol and the additional one might confuse people who read the book.
Possibly, the better way is to use // to separate command and a comment.
There was a problem hiding this comment.
the better way is to use // to separate command and a comment.
How about using # to separate command and a comment instead of //? Even if user copy whole command, they won't get any error because in most shell # sign is used for comment.
Yeah, no need to add more to this one. |
- After removing period mark from figure captions; some paragraph left with no period because those paragraph has only one period and that's because of figure caption (see progit#1444 (comment)). - End all bullet points with a period.
There is no need for period mark at end of text, present in square bracket; and removing it also make syntax consistent across whole project.
Some square brackets are empty, but they do have caption along with them. So I've put same text as caption in empty square brackets.
We generally separate statement and commands with a colon.
See @ben's comment on PR progit#1444[1]. [1]: progit#1444 (comment)
Double quote around "Home" keyword is missing in square bracket, but present in figure caption, see @Morganov's comment on PR progit#1444[1]. [1]: progit#1444 (comment)
|
@ben, I've made all suggested changes. Can you review the pull request, once again? |
|
✨ |
@ben can you take a look into this pull request? As you suggested, I've removed all punctuation mark from figure captions. Here I'm adding few screenshots after changes:
Resolves: #1437