| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <style type="text/css"> |
| p, table, td, th { font-family: verdana, arial, helvetica, geneva; font-size: 10pt} |
| pre { font-family: "Courier New", Courier, mono; font-size: 10pt} |
| h2 { font-family: verdana, arial, helvetica, geneva; font-size: 18pt; font-weight: bold ; line-height: 14px} |
| code { font-family: "Courier New", Courier, mono; font-size: 10pt} |
| sup { font-family: verdana, arial, helvetica, geneva; font-size: 10px} |
| h3 { font-family: verdana, arial, helvetica, geneva; font-size: 14pt; font-weight: bold} |
| li { font-family: verdana, arial, helvetica, geneva; font-size: 10pt} |
| h1 { font-family: verdana, arial, helvetica, geneva; font-size: 24pt; font-weight: bold} |
| body { font-family: verdana, arial, helvetica, geneva; font-size: 10pt; margin-top: 5mm; margin-left: 3mm} |
| .indextop { font-size: x-large; font-family: verdana, arial, helvetica, sans-serif; font-weight: bold} |
| .indexsub { font-size: xx-small; font-family: verdana, arial, helvetica, sans-serif; color: #8080FF} |
| a.bar:link { text-decoration: none; color: #FFFFFF} |
| a.bar:visited { color: #FFFFFF; text-decoration: none} |
| a.bar:hover { color: #FFFFFF; text-decoration: underline} |
| a.bar { color: #FFFFFF} |
| |
| body {max-width: 900px;} |
| table.news col.title {width: 30%;} |
| table.news {table-layout: fixed; border-collapse: collapse; width: 100%;} |
| table.news td {border-top: solid thin black; padding: 10px; overflow: visible;} |
| table.news tr {vertical-align: top;} |
| table.news tr td.section {font-size: 20px; font-weight: bold;} |
| table.news tr td.title {vertical-align: top; font-weight: bold;} |
| table.news tr td.content {vertical-align: top;} |
| </style> |
| <title>Eclipse "New and Noteworthy" Instructions</title> |
| </head> |
| |
| <body> |
| <h1>Eclipse "New and Noteworthy" Template and Instructions</h1> |
| <p>Last revised 2019-10-16.</p> |
| <p>This is the template for the "New and Noteworthy" document that |
| accompanies each Eclipse project milestone and release build.</p> |
| <p>Note: This template is XHTML 1.0 Transitional. Please use the W3C <a href="https://validator.w3.org/#validate_by_input">XHTML |
| Markup Validation Service</a> to check your document's markup before submitting. |
| This will detect screwed up HTML tags, images without an "alt" |
| attribute, and other tedious little details.</p> |
| |
| <ul> |
| <li><a href="#Section1">Section 1</a></li> |
| <li><a href="#Section2">Section 2</a></li> |
| <li><a href="#Section3">Section 3</a></li> |
| </ul> |
| |
| <table class="news"> |
| <colgroup> |
| <col class="title" /> |
| <col /> |
| </colgroup> |
| |
| <tr> |
| <td id="Instructions" class="section" colspan="2"> |
| <h2>Instructions</h2> |
| </td> |
| </tr> |
| |
| <tr id="content-org"> |
| <td class="title">Content Organization</td> |
| <td class="content"> |
| Starting from Eclipse 4.9, we only have 2 milestones per release. Hence, we have a rolling New and Noteworthy document for the release and do not create separate document for each milestone anymore. |
| <p>The New and Noteworthy content is contained in 4 pages and are grouped based on the component they belong to. |
| The pages are platform.html, jdt.html, platform_isv.html and pde.html. The platform_isv.html page contains the entries for new APIs in Platform, SWT and Equinox. |
| The index.html page describes the release and contains links to the component news pages. |
| </p> |
| <p>Add the entry to the appropriate section in the corresponding html document. |
| If required, you can add a new section to the document to highlight a feature, for example see : <a href="4.8/jdt.html#JUnit">JUnit support</a>. |
| </p> |
| </td> |
| </tr> |
| |
| <tr id="item-name"> |
| <td class="title">News item title and description</td> |
| <td class="content"> |
| The whole entry should be a blurb pitched to the Eclipse end user community |
| (not just to members of the Eclipse Platform development team). |
| <p> |
| The title should be short and snappy, written in |
| <a href="https://en.wikipedia.org/wiki/Letter_case#Case_styles">sentence case</a>, and using |
| "<a href="https://en.wikipedia.org/wiki/Headlinese#Syntax">headlinese</a>" (compressed style). |
| The title should <b>not</b> use trailing punctuation, and the <tr> XHTML element |
| needs a unique id attribute (value is all-lowercase and hyphen-separated). |
| </p> |
| <p> |
| In the news description, tell |
| users about changes they'll see in the UI. Tell component writers |
| about changes they'll see at the client- and server-side APIs. Try to |
| generate some excitement; save the boring details for the manual; be short and don't repeat yourself. The |
| description should be complete sentences, with trailing punctuation. |
| </p> |
| <p>Make the entry self-contained and mention API classes. |
| Do <b>not</b> link to bugs and don't promote individuals or third-party products. |
| </p> |
| <p>Use active voice (say "you", not "the user"), and follow other advice in the |
| <a href="https://wiki.eclipse.org/Eclipse_Doc_Style_Guide#topic-content">Topic Content</a> |
| section of the Eclipse Doc Style Guidelines. |
| </p> |
| <p>Stick to the default font and size. Make command names (<b>Quick Fix</b>), |
| keyboard shortcuts (<b>Ctrl+1</b>), and preference page paths |
| (<b>Preferences > General > Keys</b>) bold (using <code><</code>b<code>></code>). |
| Avoid other emphasis markup, but prefer <code><</code>b<code>></code> |
| over <code><</code>em<code>></code> if you have to use one. |
| </p> |
| <p>Do <b>not</b> enclose the first paragraph of an item in <code><p></p></code> tags. |
| Later in the entry, prefer <code><p></code> over <code><br/></code>. |
| </p> |
| <p>To break up very long <code><code></code> tags that don't contain whitespace for automatic word-wrap, |
| consider inserting <code><span style="visibility:hidden">&shy;</span></code> at strategic positions. |
| </p> |
| <p>See entries in <a href="../../4.6/M7/index.html">published</a> news documents for correct examples. These published news entries have been already reviewed, while |
| entries in the evolving document may still contain errors. |
| </p> |
| </td> |
| </tr> |
| |
| <tr id="bug-number"> |
| <td class="title">Bug number for an entry</td> |
| <td class="content"> |
| Add a link to the associated bug as a <b>comment</b> in the entry. |
| <p>This makes it easier to find the associated bug in order to get more details about the entry, add comments or report problems. |
| Also, users will be able to find the bug number associated with an entry in the news page by viewing it's html source. |
| </p> |
| For an example, see this <a href="4.9/jdt.html#show-command-line">entry</a>. |
| <p>Note: Do <b>not</b> link to bugs in the entry. |
| </p> |
| <p>Also, add the bug number in the commit message when committing the entry. |
| </p> |
| </td> |
| </tr> |
| |
| <tr id="screenshots"> |
| <td class="title">Screenshots</td> |
| <td class="content"> |
| If a small image sheds light, place it below the description, in a separate |
| paragraph. As the majority of the Eclipse users uses Windows 7, regular screen snapshots |
| should be done on Windows 7 if possible, but screenshots from |
| other operating system are also acceptable. Crop |
| out any extraneous stuff to focus the reader's attention on your new |
| feature. The image should be |
| <b>no more than 800 pixels wide</b> and in <b>PNG</b> format (as opposed |
| to GIF, TIF, BMP, or JPG). Use PNG-8 if your image doesn't have a lot of color, |
| or PNG-24 if the screen shot uses enough color to warrant additional color depth. |
| See also the |
| <a href="https://wiki.eclipse.org/Eclipse_Doc_Style_Guide#graphics">Graphics</a> |
| section of the Eclipse Doc Style Guidelines. |
| <p>The Windows <b>Snipping Tool</b> actually saves to PNG on Windows 7 and can easily be |
| used to crop and save screenshots:</p> |
| <ul> |
| <li>Arrange the windows for the shot</li> |
| <li>Use the Windows <b>Snipping Tool</b> to capture part of the screen</li> |
| <li>Use <b>File > Save As</b> to save the screenshot as a PNG</li> |
| <li>Overlays such as red circles or boxes to call out details can be done using Microsoft Paint</li> |
| </ul> |
| <p>Name the file in a way that is appropriate and specific to the item |
| (e.g., key-bindings.png, rather than something generic like image.png). |
| Use all <b>lowercase</b> letters in the image file name, including the "<b>.png</b>" |
| file extension. As a separator, use <b>hyphen</b> "<b>-</b>" rather than |
| underscore, space, or whatnot. The item's id is often a good choice for an image name.</p> |
| <p>Put all the images in a sibling directory named "images". |
| This gives XHTML like:<br/> |
| <code><img src="images/foo-view.png" alt=""/></code><br/> |
| Include a suitable <a href="https://www.w3.org/TR/html4/struct/objects.html#h-13.8"><code>alt</code></a> attribute. |
| The alt text should be empty ("") if the image just illustrates the text. |
| Only use the alt text to add information that is not accessible if the page is rendered without images. |
| Don't write <code>alt="Screenshot of <i>the XY dialog</i>"</code>. |
| Blind users shouldn't have to skip useless repetitions, but e.g. a field label can be |
| interesting unless it's already part of the description.</p> |
| <p>If the <code>alt</code> attribute text cannot sufficiently replace the image contents |
| (e.g. for a screenshot that shows source code), then enclose the img element in a link |
| to a plain ".txt" file with the same name as the image:<br/> |
| <code><a href="images/foo-view.txt"><img ...</code></p> |
| <p>The images should be left-justified (as opposed to centered). Do not embed the width and height of the image.</p> |
| <p> |
| <img src="https://www.eclipse.org/artwork/images/v2/logo-800x188.png" alt="" /> |
| </p> |
| <script type="text/javascript"> |
| //<![CDATA[ |
| document.addEventListener('load', function markOversizedImages() { |
| var imgs = document.getElementsByTagName("img"); |
| for (var i = 0; i < imgs.length; i++) { |
| var img = imgs[i]; |
| var w = window.getComputedStyle(img, null).getPropertyValue("width"); |
| if (parseInt(w, 10) > 520) { |
| img.style.width = "300px"; |
| var filter = "sepia(0.5) blur(2px)"; |
| img.style.filter = filter; |
| img.style.webkitFilter = filter; |
| var msg = document.createElement("div"); |
| msg.innerHTML = "Image too big. See Instructions > <a href='#screenshots'>Screenshots</a>.<br>" |
| + img.getAttribute("src") + ": width=" + w; |
| msg.style.color = "red"; |
| msg.style.fontWeight = "bold"; |
| img.parentElement.insertBefore(msg, img); |
| } |
| } |
| }, true); |
| //]]> |
| </script> |
| <script type="text/javascript"> |
| //<![CDATA[ |
| window.addEventListener('load', function findWrongHighLighter() { |
| var emTags = document.getElementsByTagName("em"); |
| for (var i = 0; i < emTags.length; i++) { |
| var tag = emTags[i]; |
| var msg = document.createElement("div"); |
| msg.innerHTML = "Do not use <em> for highlighting. Prefer the usage of <b>. See Instructions.<br>" |
| msg.style.color = "red"; |
| msg.style.fontWeight = "bold"; |
| tag.parentElement.insertBefore(msg, tag); |
| } |
| }, true); |
| //]]> |
| </script> |
| </td> |
| </tr> |
| <tr id="css"> |
| <td class="title">CSS styling</td> |
| <td class="content"> |
| Do <b>not</b> change the style.css file without consulting with the Eclipse Platform project lead. The news entries are |
| aggregated at the end of the development cycle and the CSS files need to be aligned. |
| </td> |
| </tr> |
| <tr id="validation"> |
| <td class="title">Validation</td> |
| <td class="content"> |
| Use the W3C <a href="https://validator.w3.org/#validate_by_input">XHTML |
| Markup Validation Service</a> to check your document's markup before |
| submitting. |
| <p> |
| Run <b>scripts/validateHtmlNewsRepo.sh</b> to validate the html files in a release folder using a script. |
| Instructions can be found in scripts/instructions.txt. |
| </p> |
| </td> |
| </tr> |
| <tr id="init"> |
| <td class="title">Initialization</td> |
| <td class="content"> |
| To create the directory and all the related content for a new release, use the 4.x-template directory. |
| Replace 4.x in the html files with the eclipse project's release version and YYYY-MM with the SimRel release name. |
| <p> |
| Run <b>scripts/applyTemplate.sh</b> to automatically do these steps for you. |
| Instructions to run the script can be found in scripts/instructions.txt. |
| </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td colspan="2" class="section" id="Section1">Section 1</td> |
| </tr> |
| |
| <tr id="first-item-Section1"> |
| <td class="title">First item</td> |
| <td class="content"> |
| Item blurb. |
| </td> |
| </tr> |
| |
| |
| <tr> |
| <td colspan="2" class="section" id="Section2">Section 2</td> |
| </tr> |
| |
| <tr id="first-item-Section2"> |
| <td class="title">First item</td> |
| <td class="content"> |
| Item blurb. |
| </td> |
| </tr> |
| |
| |
| <tr> |
| <td colspan="2" class="section" id="Section3">Section 3</td> |
| </tr> |
| |
| <tr id="first-item-Section3"> |
| <td class="title">First item</td> |
| <td class="content"> |
| Item blurb. |
| </td> |
| </tr> |
| |
| <tr> |
| <td colspan="2"/> |
| </tr> |
| </table> |
| </body> |
| </html> |