<HTML>
<HEAD>
<TITLE>Guidelines for working on www.netbeans.org</TITLE>
<META NAME="description" CONTENT="Guidelines specific to working on content on the www website">
<link rel="stylesheet" type="text/css" HREF="../../netbeans.css">
</HEAD>

<BODY>

<h1>Working With Content on www</h1>

<UL>
  <li><a href="#intro">Introduction</a>
  <li><a href="#guidelines">Some Guidelines</a>
  <ul>
    <li><a href="#managed">Managed Content</a>
    <li><a href="#new">New Content</a>
    <li><a href="#naming">Naming Conventions</a>
    <li><a href="#images">Images</a>
    <li><a href="#bigimages">Big Images</a>
    <li><a href="#binaries">Large Binary Files</a>
    <li><a href="#links">Relative Links</a>
    <li><a href="#dynamic">Dynamic Pages</a>
    <li><a href="#style">Style and Formatting</a>
    <li><a href="#breadcrumbs">Breadcrumbs</a>
  </ul>
  <li><a href="#perms">Got Permissions ?</a>
  <li><a href="#updates">Submitting updates</a>
  <li><a href="#offsite">Submitting Links to Off-Site Docs</a>
  <li><a href="#translate">Translating Content</a>
  <li><a href="#rightcol">The Right Column</a>
</UL>

<h2><a name="intro">Introduction</a></h2>
<p>This guide is intended for anyone who would like to submit
content for the www.netbeans.org site (www specifically, not
the module websites like core.netbeans.org).  "Submitting
content" might mean corrections or updates to existing docs,
completely new docs, or translated versions of some docs.</p>

<p>The web-content repository is under SVN version control and can
be checked out. However the <a HREF="../teams/web/index.html">NetBeans Web Team</a>
have implemented a publishing system for www, and adding or editing
content there is quite different than for other module websites.

<h2><a name="guidelines"></a>Some Guidelines</h2>

<p>Please observere the following guidelines when commiting to the site :

<ul>

<li><a name="managed"></a>
  <p><b>Managed Content?</b>
  <br>The www website is partly "managed content", owned by the Web and
  Evangelism teams.  Any significant changes, or changes to higher-level
  product info pages should be approved by the Evangelism and/or web teams
  before publishing.  If you're working on such a page, please forward your changes to
  <a href="../../about/contact_form.html?to=1">webmaster</a> and the
  <a href="../../about/contact_form.html?to=2">evangelism team</a>,
  including some background about why you want to make these changes.</p>

<li><a name="new"></a>
  <b>New Content</b>
  <br>Navigation and site layout is carefully controlled, to make sure
  content is logically structured, in a coherent and consistent way.  If
  you are adding new content, please check with the 
  <a href="../../about/contact_form.html?to=1">webmaster</a> where would
  be the best place to add your file(s), and how to link that with the
  rest of the site.

<li><a name="naming"</a>
  <b>Naming Conventions</b>
  <br>Again, if you are adding a <I>new</I> file, please try to use filenames
  consistent with existing naming conventions.  These are obviously not
  critical, but please try to observe them.  Some basic guidelines :

  <p><ul>
    <li>Don't use spaces in file or directory names;

    <p><li>A NetBeans version number should not be needed in the filename.
      Version-based directory structure is standard, so a filename need not
      include a version number.  Eg :
      <blockquote>Good : kb/60/hello-world.html
      <br><i>BAD : kb/hello-world-60.html</i>
    </blockquote>

    <li>Don't use underscores (except for localised content language extension like index_ru.html).  Eg :
      <blockquote>Good : community/guidelines/file-naming.html
      <br><i>BAD : community/guidelines/file_naming.html</i>
      </blockquote>

    <!-- <li>Don't use mixed case in filenames (camelCase).  Windows does not differentiante
      between upper and lower case in filenames, which can cause problems and clashes in CVS.
      See eg <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=57402">issue 57402</a> which
      deals with this problem.  Eg :
      <blockquote>Good : file-name.html
      <br><i>BAD : fileName.html</i>
      <br><i>BAD : file.PNG</i>
      <br><i>BAD : FILE.PNG</i>
      </blockquote> -->
  </ul>

<li><a name="images"></a>
  <b>Images</b>
  <br>If you're adding images to the site, please
  put them under the root images_www directory.  If you're creating an article with
  several images, it probably makes sense to create a new images dir for them,
  e.g. images/articles/67/midp-guide/.

<li><a name="bigimages"></a>
  <b>Big Images</b>
  <br>
  Using wide images in your content will force
  the page to be wide, and depending on a viewer's screen resolution this may
  cause a horizontal scrollbar to appear - yuck!  The minimum target resolution
  netbeans.org is designed for is 1024 x 768px, which means the main content area
  should be at maximum 600px wide.  If you have any images wider than 600px,
  please create scaled-down versions of them for use in your article.  <br />
  To make sure visitors can see the real image
  and any detail lost by the scaling, you should link the small version to
  the fullsize version, so viewers can click to see it in all it's glory.
  Here is an example:
  <pre>&lt;a href="../../../images_www/articles/quickstart-web/palette.png">
    &lt;img src="../../../images_www/articles/quickstart-web/palette_small.png" border="0">&lt;/a></pre>

  <br><br>If you're not comfortable resizing your images, the Web Team can help,
  just <a href="../../about/contact_form.html?to=1">get in touch</a>
  with details of what you need.

<li><a name="binaries"></a>
  <b>Large Binary Files</b>
  <br>It is preferrable to keep large binary files <I>out</I> of the version controlled
  repositories.  If you need to put a big file on the site, for example a zipfile
  of sources, a jar, or a .swf flash file, please use
  <a href="https://netbeans.org/projects/help/pages/Downloads">the file upload feature</a>.
  This utility allows uploading and maintenance of all kinds of files.  Once your
  file is in place, you can link to it from your html pages.
  <br><br>If you don't have permissions to add a file to the utlity on www, you
  could try adding it to contrib.netbeans.org.  If you have no
  permissions on any modules, contact the 
  <a href="../../about/contact_form.html?to=1">webmaster</a> with details of
  what you're trying to do.

<li><a name="links"></a>
  <b>Relative Links</b>
  <br>Please use relative links in your html, such as &lt;a href="../../directory/file.html"&gt;,
  rather than absolute (like "/directory/file.html") or fully qualified (like "https://netbeans.org/directory/file.html").
  This way your (and everyone else working on the site's) local checkout
  is browseable, the links work, and go to your local copies.

<li><a name="dynamic"></a>
  <b>Dynamic Pages</b>
  <br>While all content in web-content is static html, some pages are
  automatically generated by a content management system, and then uploaded as static
  snapshots.  The home page is an example - several sections (headlines,
  articles, etc) are generated and updated dynamically by the Web Team.
  <em>Any edits you make to a dynamic page will be lost when the page will be
  next auto-generated.</em>  All such pages include a warning comment in the html
  source :

  <blockquote><pre>
  &lt;!-- ====================================================== --&gt;
  &lt;!-- Please do not edit this file by hand, it is rebuilt    --&gt;
  &lt;!-- automatically and your changes will be lost.  Contact  --&gt;
  &lt;!-- webmaster for details.  Rebuilt at                     --&gt;
  &lt;!-- #TIMESTAMP# .................                          --&gt;
  &lt;!-- ====================================================== --&gt;
  </pre></blockquote>

  <p>If you see such a warning in a file, you will need to ask the
  <a href="../../about/contact_form.html?to=1">webmaster</a> to make your changes.</p>

<li><a name="style"></a><b>Style and Formatting</b>
  <p>Please try to use standard styles, layout, and formatting for any new
  pages.  Please refer to the <a HREF="web-guide.html#templates">templates
  section</a> of the webguide, and <a HREF="css-guide.html">the CSS guide</a>
  for help.  When in doubt, just copy the source of an existing page which suits
  your needs.</p>

<p><a name="breadcrumbs"></a><li><b>Breadcrumbs</b>
  <p>The breadcrumb navigation trail across the top of the page is automatically
  generated.  The breadcrumbs are directory
  based - as a visitor browses deeper into the site hierarchy, an item is
  added to the breadcrumb list for each directory.  </p>

</ul>

<h2><a name="perms"></a>Got Permissions ?</h2>
<p>If you have write permissions for web-content, and you are
comfortable with how the publishing system works, it's probably fine to
go ahead and commit your changes yourself.  If you don't have permissions,
or are not 100% comfortable with SVN and/or HTML, please see the
<a href="#updates">Submitting Updates</a> section below.</p>

<p>When your file is ready, the procedure to commit your files
is the same for any SVN commit.</p>

<P><OL>
  <LI>Checkout the website content (<b>web-content</b>).  If you do :

  <P><TT>svn co https://svn.netbeans.org/svn/web-content~web-content/trunk</TT> 

  <P>you will get the full website - including images, so it is quite
  large and might take a while.

  <P><LI>Make your updates/additions. web-content/www maps to the docroot of
  https://netbeans.org/, so for e.g. to edit

  <P><TT>https://netbeans.org/directory1/file2.html</TT>

  <P>look for the file

  <P><TT>trunk/web-content/www/directory1/file2.html</TT>

  <P>Edit or create your file and check your changes in a browser to
  make sure all looks good.

  <P><LI>If you are editing and existing file, check nobody else has
  edited the file since you started:

  <P><TT>$ svn update dir1/file2.html</TT>

  <P>If you are adding a new file, add it to the SVN repository:

  <P><TT>$ svn add dir1/file2.html</TT> 

  <P>Assuming all is well, go ahead and commit it:

  <P><TT>$ svn commit -m "brief informative message about this update" dir1/file2.html</TT> 

  <P>You can immediately view your changes on the web site, so double
  check them.  Browse to https://netbeans.org/dir1/file2.html .

</OL>

<p><h2><a name="updates">Submitting Updates</a></h2></p>
<p>If you don't have a netbeans.org account, or permissions to commit to web-content,
and you've found something on the site that needs updating, please
let us know about it.  Even better, contribute the updated content!  </p>

<p>There are a few preferred methods for submitting updates -
using one of the following methods will help the webmasters to
quickly and easily verify your changes and apply them.</p>

<UL>
  <LI><B>Submit a patch for the HTML</B>.  This is by far the easiest for the webmasters
  and should ensure the fix is applied and goes live fastest.  The following
  example uses the Unix command line SVN, if you are using Windows or a GUI client
  the basic procedure should be the same.

  <P><OL>
  <LI>Checkout the website content.  If you do :

  <P><TT>svn co https://svn.netbeans.org/svn/web-content~web-content/trunk</TT>

  <P>you will get the full website - including images, so it is quite
  large and might take a while.

  <P><LI>Make your updates.  Find the file you want to update. 
      trunk/web-content/www/
  maps to the docroot of https://netbeans.org/, so for eg to edit

  <P><TT>https://netbeans.org/directory1/file2.html</TT>

  <P>look for the file

  <P><TT>trunk/web-content/www/directory1/file2.html</TT>

  <P>Edit the file and check your changes in a browser to make sure all
  looks good.

  <P><LI>Make the patch.  Once you're done with your edits, from the
  command line, do :

  <P><TT>$ cd trunk/web-content/www/
  <BR>$ svn diff -u directory1/file2.html > file2.patch</TT>

  <P>Replacing directory1 and file2.html with the real location and
  filename of course.

  <P><LI>Submit your patch!  Either file an issue, adding the patch as an
  attachment, or simply email it to
  <a href="https://netbeans.org/about/contact_form.html?to=1">webmaster</a>.
  Please explicitly summarise what the patch is for, and why you
  think it's needed.
  </OL>

  <P><LI><B>Submit the whole updated HTML file</B>.  If you'd rather
  not use SVN or checkout the site, you can send in the updated
  HTML file.

  <P><OL>
  <LI>Browse to the print version of the page.  First find the page on the
  www site, and then click "printable version" at the top.
  You'll see the same page, minus navigation, logos etc.

  <P><LI>Edit the HTML source.  Select the View -&gt; Source menu item
  in your browser.  Select all of the source, and save it as plain text file
  somewhere on your system.  Edit the page as you wish, and check your
  changes in a browser to make sure all looks good.

  <P><LI>Submit the file!  Either file an issue, adding the updated file as an
  attachment, or simply email it to
  <a href="https://netbeans.org/about/contact_form.html?to=1">webmaster</a>.
  Please explicitly summarize what the updates are, and for which file, and why
  you think it's needed.
  </OL>

  <P><LI><B>Just submit the text of your updates!</B>.  Obviously quickest
  and easiest to do, but might take more time for the webmasters to check
  and apply your suggestions.
</UL>

<P><h2><a name="offsite">Submitting Links to Off-Site Docs</a></h2></p>
<p>If there's content hosted on some other site that you think is
relevant to netbeans.org, <a href="https://netbeans.org/about/contact_form.html?to=1">send us the link</a>,
including a brief description of what the article is about.</p>

<P><h2><a name="translate">Translating Content</a></h2></p>
<p>If you're interested in translating either web content or the IDE itself
into your native language, we'd love your help.  See the following guides
to get started :</p>

<ul>
  <li><a href="../contribute/localise.html">Translating html content for the netbeans.org website</a>
  <li><a href="http://nblocalization.netbeans.org//">Translating the NetBeans IDE</a>
</ul>

<P><h2><a name="rightcol">The Right Column</a></h2></p>
<p>To add content to the right column of a page on www, you need to put that
content in a special .inc file.  The .inc file is not a standalone html file,
<b>it should not include any &lt;head&gt;, &lt;title&gt; or &lt;body&gt; tags!</b>
Just the content you want, eg styled text.</p>

<p>The .inc file must live in the same directory as the main parent file.  The
filename is critical - it should always take the form ${parent_filename}.inc.html.
This is perhaps best explained by looking at some examples :</p>

<div style="float:left; padding-left:30px; width:300px; font-weight:bold;">For file ...</div><div style="margin-left:300px; font-weight:bold;">Put right col content in ...</div>
<div style="float:left; padding-left:30px; width:300px;">downloads.html</div><div style="margin-left:300px;">downloads.inc.html</div>
<div style="float:left; padding-left:30px; width:300px;">community/releases/roadmap.html</div><div style="margin-left:300px;">community/releases/roadmap.inc.html</div>
<div style="float:left; padding-left:30px; width:300px;">features/ide/index_ru.html</div><div style="margin-left:300px;">features/ide/index_ru.inc.html</div>
<div style="float:left; padding-left:30px; width:300px;">kb/60/using-netbeans/ant_zh_CN.html</div><div style="margin-left:300px;">kb/60/using-netbeans/ant_zh_CN.inc.html</div>


</body>
</html>