I work with mercurial, and use long(ish), multi-line commit comments.
Recently, I've put my project on BitBucket.org, and have noticed that when my commit comments are appended to issue pages (see this SO question for information on how/when that happens), the newlines are replaced with spaces, while double-newlines stay double-newlines.
How should I mark single-newlines in commit messages so that BitBucket acknowledges them? I'd like to do this in the least-obtrusive way for when I read the comments normally from the command line.
Break paragraphs (generating <p> tags) with a blank line. Break lines (generating a <br> tag) by ending the first line with two or more spaces, e.g.
Line one␣␣
Line two
Bitbucket formats comments using Markdown, which has this to say about paragraphs and line breaks:
Paragraphs and Line Breaks
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.
The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard-wrapped" text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s "Convert Line Breaks" option) which translate every line break character in a paragraph into a <br /> tag.
When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.
Yes, this takes a tad more effort to create a <br />, but a simplistic "every line break is a <br />" rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.
Related
I can't find a guideline on how to indent HTML tags on multiple line, and the solution I am currently using doesn't really satisfy me.
Imagine we have an extremely long div declaration, such as:
<div data-something data-something-else data-is-html="true" class="html-class another-html-class yet-another-html-class a-class-that-makes-this-declaration-extremely-long" id="just-a-regular-id">
In order to avoid scrolling horizontally when I find these huge lines, I usually indent them in the following way:
<div
data-something
data-something-else
data-is-html="true"
class="html-class another-html-class yet-another-html-class a-class-that-makes-
this-declaration-extremely-long"
id="just-a-regular-id"
>
<p>Some element inside the DIV</p>
</div>
Which I think works pretty well in terms of readability, but I have some concern.
Is this way considered a good practice?
Would you find more readable to leave the closing > in the opening HTML Tag inline with the last element, or on a new line as I did in the example above?
Do you have any other preferred way to deal with extremely long HTML declaration?
Feel free to share if you know some good resource about style guidelines for HTML that cover this special case, because I didn't find anything specific online.
The Google HTML/CSS Style Guide suggests wrapping long lines when it significantly improves readability, and offers three techniques, each of which include the closing > with the last line of attributes:
Break long lines into multiple lines of acceptable length:
<div class="my-class" id="my-id" data-a="my value for data attribute a"
data-b="my value for data attribute b" data-c="my value for data attribute c">
The content of my div.
</div>
Break long lines by placing each attribute on its own indented line:
<div
class="my-class"
id="my-id"
data-a="my value for data attribute a"
data-b="my value for data attribute b"
data-c="my value for data attribute c">
The content of my div.
</div>
Similar to #2 except the first attribute is on the initial line, and subsequent attributes are indented to match the first attribute:
<element-with-long-name class="my-class"
id="my-id"
data-a="my value for data attribute a"
data-b="my value for data attribute b"
data-c="my value for data attribute c">
</element-with-long-name>
In my opinion, #3 would not improve readability when the element contains content.
Personally I find it to be a good practice and I find it more readable using multiple lines. I use the same convention for websites that I make.
In my college we are taught the same convention and it clearly states:
Avoid Long Code Lines
When using an HTML editor, it is inconvenient to scroll right and left to read the HTML code.
Try to avoid code lines longer than 80 characters.
The rest of the convention can be found here:
https://www.w3schools.com/html/html5_syntax.asp
Would you find more readable to leave the closing > in the opening HTML Tag inline with the last element, or on a new line as I did in the example above?
I think leaving the closing > is more readable but when use vscode it can't fold properly.
Unexpected,
Expected,
The following, is my preferred method:
<div
class="my-class"
id="my-id"
data-a="my value for data attribute a"
data-b="my value for data attribute b"
data-c="my value for data attribute c"
>The content of my div.
</div>
The crucial detail here is the lack of space between the closing > and the actual content.
All the following examples can be checked online:
€<span itemprop="price">13.50</span>
results in €13.50
€<span
itemprop="price"
Arbitrary carriage returns and spaces here
BUT before closing the tag
>13.50
</span>
also results in €13.50
However
€<span
itemprop="price"> <!-- Carriage return + spaces in this line -->
13.50
</span>
or
€ <!-- Carriage return + spaces in this line -->
<span
itemprop="price"> <!-- Carriage return + spaces in this line -->
13.50
</span>
Both result in € 13.50 (Mind the gap!)
I have the following HTML body:
<a name="milosz"><h2>Learning</h2></a>
To believe you are magnificent. <br>
And gradually to discover that you are not magnificent.<br>
Enough labor for one human life.<br>
<br>
<br>
In the web page it appears like this:
To believe you are magnificent.
And gradually to discover that you are not magnificent.
Enough labor for one human life.
Note that the from second line onwards the sentences are indented.
Is there a way to avoid such indentation?
You start another line when using a line break with <br>. When followed with a space (which is the ASCII value of a space), naturally this starts the new line with a space. Try removing .
Your case
Code
First line<br>
Second line
Result
First line
Second line
Solution
Code
First line<br>
Second line
Result
First line
Second line
<br> -- Line Break (New Line)
-- For Blank Space
You have written in the end of every line this is for new line (Line Break) and for Indent you are using this is to space
so remove and to keep this in single line.
Use pre tag Like
open (pre) tag
formate
you
want
to show
Close (pre) tag
I'm trying to create a two-line <h1> in Markdown, something along the lines of:
<h1>Title<br/>byline</h1>
The Markdown docs say:
When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.
Unfortunately, this only seems to work for paragraphs -- if I try it with an <h1> (dots · indicate spaces):
#·Title··
byline
the trailing spaces are ignored and I just get:
<h1>Title</h1>
<p>byline</p>
Can anyone tell me a workaround for this?
P.S. I'm using vanilla Markdown 1.0.1 from the command line.
Turns out the answer is just "use <br/>."
# Title <br/> byline
produces
<h1>Title <br/> byline</h1>
** facepalm **
Just use the alternative syntax for <h1>:
Title··
byline
========
You can also do double space at the end of the line.
For example, this text appears in the same line even though I've written it on the next line.
This appears on a new line.
The thing is there are 2 blank spaces after next line... (Consider those two dots as spaces)
Hope this helps. This also seems better than </BR>.
Reference: http://markdown-guide.readthedocs.io/en/latest/basics.html
I'm using Maruku (Ruby) to parse some Markdown formatted text. I have a problem when trying to format a block of code like such:
This is a normal line
# pretend this line is empty
printf("First line of code is OK");
printf("Second line of code (or any line thereafter) appears indented by an extra level, which is incorrect!");
So my first line of code (which I've indented in my md file by 4 spaces (or a tab), renders just as I'd expect. However, my second line of code (indented by exactly the same number of spaces) ends up being indented by an extra 4 spaces when the HTML is generated.
The output looks like this:
This is a normal line
<pre><code>printf("First line of code is OK");
printf("Second line of code (or any line thereafter) appears indented by an extra level, which is incorrect!");</code></pre>
I've tested my Markdown input with Gruber's "Dingus", and it renders as I'd expect (that is, both lines of code in a single block, both indented at the same level). But with Maruku, it's bunk.
I've also tried with RDiscount, but I get the same effect. I'm using Maruku because I need definition lists.
How SO formats it:
This is a normal line
printf("First line of code is OK\n");
printf("Second line of code (or any line thereafter) appears indented by an extra level, which is incorrect!");
It turns out this was not a Maruku problem but a HAML problem.
HAML is fussy when it comes to whitespace and preserving it. The solution was needing to use = preserve #my_html_string when rendering it.
For example, given layout.haml:
!!! 5
%html
%body
= yield
and index.haml
%article
= preserve #my_html_fragment_with_pre_and_code
Then it would render correctly for me.
Why indeed? Wouldn't something like &br; be more appropriate?
An HTML entity reference is, depending on HTML version either an SGML entity or an XML entity (HTML inherits entities from the underlying technology). Entities are a way of inserting chunks of content defined elsewhere into the document.
All HTML entities are single-character entities, and are hence basically the same as character references (technically they are different to character references, but as there are no multi-character entities defined, the distinction has no impact on HTML).
When an HTML processor sees, for example — it replaces it with the content of that entity reference with the appropriate entity, based on the section in the DTD that says:
<!ENTITY mdash CDATA "—" -- em dash, U+2014 ISOpub -->
So it replaces the entity reference with the entity — which is in turn a character reference that gets replaced by the character — (U+2014). In reality unless you are doing this with a general-purpose XML or SGML processor that doesn't understand HTML directly, this will really be done in one step.
Now, what would we replace your hypothetical &br; with to cause a line-break to happen? We can't do so with a newline character, or even the lesser known U+2028 LINE SEPARATOR (which semantically in plain text has the same meaning as <br/> in HTML), because they are whitespace characters which are not significant in most HTML code, which is something that you should be grateful for as writing HTML would be much harder if we couldn't format for readability within the source code.
What we need is not an entity, but a way to indicate semantically that the rendered content contains a line-break at this point. We also need to not indicate anything else (we can already indicate a line-break by beginning or ending a block element, but that's not what we want). The only reasonable way to do so is to have an element that means exactly that, and so we have the <br/> element, with its related tag being put into the source code.
A tag and a character entity reference exist for different reasons - character entities are stand-ins for certain characters (sometimes required as escape sequences - for example & for an ampersand &), tags are there for structure.
The reason the <br> tag exists is that HTML collapses whitespace. There needs to be a way to specify a hard line break - a place that has to have a line break. This is the function of the <br> tag.
There is no single character that has this meaning, though U+2028 LINE SEPARATOR has similar meaning, and even if it were to be used it would not help as it is considered to be whitespace and HTML would collapse it.
See the answers from #John Kugelman and #John Hanna for more detail on this aspect.
Not entirely related, there is another reason why a &br; character entity reference does not exist: a line break is defined in such a way that it could have more than one character, see the HTML 4 spec:
A line break is defined to be a carriage return (
), a line feed (
), or a carriage return/line feed pair.
Character entities are single character escapes, so cannot represent this, again in the HTML 4 spec:
A character entity reference is an SGML construct that references a character of the document character set.
You will see that all the defined character entities map to a single character. A line break/new line cannot be cleanly mapped this way, thus an entity is required instead of a character entity reference.
This is why a line break cannot be represented by a character entity reference.
Regardless, it not not needed as simply using the Enter key inserts a line break.
Entities are stand-ins for other characters or bits of text. In HTML they are used to represent characters that are hard to type (e.g. — for "—") or for characters that need to be escaped (& for "&"). What would a hypothetical &br; entity stand for?
It couldn't be \r or \n or \r\n as these are already easy enough to type (just press enter). The issue you're trying to workaround is that HTML collapses whitespace in most contexts and treats newlines as spaces. That is, \n is not a line break character, it is just whitespace like tabs and spaces.
An entity &br; would have to be replaced by some other text. What character do you use to represent the concept of "hard line break"? The standard line break character \n is exactly the right character, but unfortunately it's unsuitable since it's thrown in the generic "whitespace" bucket. You'd have to either overload some other control character to represent "hard line break", or use some extended Unicode character. When HTML was designed Unicode was only a nascent, still-developing standard, so that wasn't an option.
A <br> element was the simple, straightforward way to add the concept of "hard line break" to a document since no character could represent that concept.
In HTML all line breaks are treated as white space:
A line break is defined to be a carriage return (
), a line feed (
), or a carriage return/line feed pair. All line breaks constitute white space.
And white space does only separate words and sequences of white space is collapsed:
For all HTML elements except PRE, sequences of white space separate "words" (we use the term "word" here to mean "sequences of non-white space characters"). […]
[…]
Note that a sequence of white spaces between words in the source document may result in an entirely different rendered inter-word spacing (except in the case of the PRE element). In particular, user agents should collapse input white space sequences when producing output inter-word space. […]
This means that line breaks cannot be expressed by plain characters. And although there are certain special characters in Unicode to unambiguously separate lines and paragraphs, they are not specified to do this in HTML too:
Note that although
and
are defined in [ISO10646] to unambiguously separate lines and paragraphs, respectively, these do not constitute line breaks in HTML […]
That means there is no plain character or sequence of plain characters that is to mark a line break in HTML. And that’s why there is the BR element.
Now if you want to use &br; instead of <br>, you just need to declare the entity br to represent the value <br>:
<!ENTITY br "<br>">
Having this additional entity named br declared, a general-purpose XML or SGML processor will replace every occurrence of the entity reference &br; with the value it represents (<br>). An example document:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd" [
<!ENTITY br "<br>">
]>
<HTML>
<HEAD>
<TITLE>My first HTML document</TITLE>
</HEAD>
<BODY>
<P>Hello &br;world!
</BODY>
</HTML>
Entities are content, tags are structure or layout (very roughly speaking). It seems whoever made the <br> a tag decided that breaking a line has more to do with structure and layout than with content. Not being able to actually "see" a <br>
I'd tend to agree. Oh and I'm making this up as I go so feel free to disagree ;)
HTML is a mark-up language - it represents the structure of a document, not how that document should appear visually. Take the <EM> tag as an example - it tells user-agents that they should give emphasis to any text that is placed between the opening and closing <EM> tags. However, it does not state how that emphasis should be represented. Yes, most visual web-browsers will place the text in italics, but this is only convention. Other browsers, such as monochrome text-only browsers may display the text in inverse. A screen reader might read the text in a louder voice, or change the pronunciation. A search-engine spider might decide the text is more important than other elements.
The same goes for the <BR> tag - it isn't just another character entity, it actually represents a break in the document structure. A <BR> is not just a replacement for a newline character, but is a "semantic" part of the document and how it is structured. This is similar to the way an <H1> is not just a way of making text bigger and bolder, but is an integral part of the way the document is structured.
br elements can be styled, though. How would you style an HTML entity? Because they're elements it makes them more flexible.
Yes. An HTML entity would be more appropriate, as a break tag cannot contain text and behaves much like a newline.
That's just not the way things are, though. Too late. I can't tell you the number of non-XML-compatible HTML documents I've had to deal with because of unclosed break tags...