* [ANN] olddoc 1.2.0 - old-fashioned RDoc generator
@ 2016-01-09 22:34 7% Eric Wong
0 siblings, 0 replies; 2+ results
From: Eric Wong @ 2016-01-09 22:34 UTC (permalink / raw)
To: ruby-talk, olddoc-public
olddoc contains old-fashioned document generators for those who do not
wish to impose bloated, new-fangled web cruft on their readers.
olddoc contains oldweb, an HTML generator without any images, frames,
CSS, or JavaScript. It is designed for users of text-based browsers
and/or low-bandwidth connections. oldweb focuses on text as it is
the lowest common denominator for accessibility and compatibility
with people and hardware.
== Reasons
* No CSS. Encouraging users to use CSS leads to problems like
copy-paste hijacking: http://thejh.net/misc/website-terminal-copy-paste
External CSS also increases page load time as it often blocks page
rendering. Asynchronous loading of CSS also causes accessibility
problems as links/buttons may move as a user attempts to click.
* No JavaScript. There is a constant barrage of security and
client-side performance problems associated with it. It's also
unreasonable to expect users to rely on LibreJS and inspect every
piece of JS they run.
* No frames. Frames are an accessibility hassle and unfriendly
to users of tiny screens on mobile devices and text-based browsers.
* No images. Not everyone can view or afford bandwidth to load images.
This also reduces the potential for security vulnerabilities as less
code gets run. Furthermore, loading the wrong image in a public
place can get you arrested (or worse).
Encourage readers to simplify and speed up their browsing experience.
They can disable CSS, JavaScript, and images in their browser without
missing out!
== Usage
gem install olddoc
cd $ANY_RDOC_USING_RUBY_PROJECT
rdoc -f oldweb
== Changes
olddoc 1.2.0 - multiple archive URLs
Users using .olddoc.yml to add links to mailing list archives
will now be pleased to know "ml_url" and "nntp_url" fields
accept arrays.
This release also fixes bold highlighting of the current
module/class page for APIs.
7 changes since 1.1.2:
bold class bar to highlight current page
copyright updates for 2016
tail: shorten the footer section
head: use old-style <meta> tags for compatibility
nodoc some internals
tail: support multiple URLs for archives
tail: fix divider when private email does not exist
* http://80x24.org/olddoc/ - homepage + sample
* http://80x24.org/olddoc-public/ - ML archives
* nntp://news.public-inbox.org/inbox.comp.lang.ruby.olddoc
* olddoc-public@80x24.org - public mailing list
* git clone git://80x24.org/olddoc
* license: GPL-3.0+
--
EW
^ permalink raw reply [relevance 7%]
* [PATCH 5/4] nodoc some internals
@ 2016-01-07 3:37 5% ` Eric Wong
0 siblings, 0 replies; 2+ results
From: Eric Wong @ 2016-01-07 3:37 UTC (permalink / raw)
To: olddoc-public
We don't want to advertise an API we'd have to support
long-term
---
lib/olddoc.rb | 4 ++--
lib/olddoc/gemspec.rb | 2 +-
lib/olddoc/history.rb | 2 +-
lib/olddoc/merge.rb | 2 +-
lib/olddoc/news_atom.rb | 2 +-
lib/olddoc/news_rdoc.rb | 2 +-
lib/olddoc/prepare.rb | 2 +-
lib/olddoc/readme.rb | 2 +-
lib/oldweb.rb | 52 +++++++++++++++++++++++++++----------------------
lib/rdoc/discover.rb | 2 ++
10 files changed, 40 insertions(+), 32 deletions(-)
diff --git a/lib/olddoc.rb b/lib/olddoc.rb
index 1621f85..d9bc384 100644
--- a/lib/olddoc.rb
+++ b/lib/olddoc.rb
@@ -1,7 +1,7 @@
# Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
-module Olddoc
- VERSION = '1.1.2'
+module Olddoc # :nodoc:
+ VERSION = '1.1.2' # :nodoc:
autoload :Gemspec, 'olddoc/gemspec'
autoload :History, 'olddoc/history'
diff --git a/lib/olddoc/gemspec.rb b/lib/olddoc/gemspec.rb
index f5f008d..f9f6417 100644
--- a/lib/olddoc/gemspec.rb
+++ b/lib/olddoc/gemspec.rb
@@ -1,7 +1,7 @@
# Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
# helper methods for gemspecs
-module Olddoc::Gemspec
+module Olddoc::Gemspec # :nodoc:
include Olddoc::Readme
def extra_rdoc_files(manifest)
diff --git a/lib/olddoc/history.rb b/lib/olddoc/history.rb
index 595994d..dcdf0fe 100644
--- a/lib/olddoc/history.rb
+++ b/lib/olddoc/history.rb
@@ -2,7 +2,7 @@
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
require 'uri'
-module Olddoc::History
+module Olddoc::History # :nodoc:
def initialize_history
@tags = @old_summaries = nil
end
diff --git a/lib/olddoc/merge.rb b/lib/olddoc/merge.rb
index b5dae65..de5e2ae 100644
--- a/lib/olddoc/merge.rb
+++ b/lib/olddoc/merge.rb
@@ -1,7 +1,7 @@
# Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
-class Olddoc::Merge
+class Olddoc::Merge # :nodoc:
def initialize(opts)
@merge_html = opts["merge_html"] || {}
end
diff --git a/lib/olddoc/news_atom.rb b/lib/olddoc/news_atom.rb
index a093e64..a9e8002 100644
--- a/lib/olddoc/news_atom.rb
+++ b/lib/olddoc/news_atom.rb
@@ -2,7 +2,7 @@
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
require 'builder'
-module Olddoc::NewsAtom
+module Olddoc::NewsAtom # :nodoc:
include Olddoc::History
include Olddoc::Readme
diff --git a/lib/olddoc/news_rdoc.rb b/lib/olddoc/news_rdoc.rb
index e8c6a34..2427591 100644
--- a/lib/olddoc/news_rdoc.rb
+++ b/lib/olddoc/news_rdoc.rb
@@ -4,7 +4,7 @@
#
require 'tempfile'
-module Olddoc::NewsRdoc
+module Olddoc::NewsRdoc # :nodoc:
include Olddoc::History
def puts_tag(fp, tag)
diff --git a/lib/olddoc/prepare.rb b/lib/olddoc/prepare.rb
index f42bd04..f902fff 100644
--- a/lib/olddoc/prepare.rb
+++ b/lib/olddoc/prepare.rb
@@ -2,7 +2,7 @@
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
require 'uri'
-class Olddoc::Prepare
+class Olddoc::Prepare # :nodoc:
include Olddoc::NewsRdoc
include Olddoc::NewsAtom
include Olddoc::Readme
diff --git a/lib/olddoc/readme.rb b/lib/olddoc/readme.rb
index 423d18b..0b3ee97 100644
--- a/lib/olddoc/readme.rb
+++ b/lib/olddoc/readme.rb
@@ -2,7 +2,7 @@
# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
# helpers for parsing the top-level README file
-module Olddoc::Readme
+module Olddoc::Readme # :nodoc:
def readme_path
'README'
diff --git a/lib/oldweb.rb b/lib/oldweb.rb
index af62050..a5da1cc 100644
--- a/lib/oldweb.rb
+++ b/lib/oldweb.rb
@@ -8,11 +8,15 @@ require 'yaml'
require 'cgi'
require 'uri'
+# oldweb is an \RDoc template and not intended as a programming API.
+# You may specify it as an \RDoc formatter:
+#
+# rdoc -f oldweb ...
class Oldweb
- RDoc::RDoc.add_generator(self)
- include ERB::Util
- attr_reader :class_dir
- attr_reader :file_dir
+ RDoc::RDoc.add_generator(self) # :nodoc:
+ include ERB::Util # :nodoc:
+ attr_reader :class_dir # :nodoc:
+ attr_reader :file_dir # :nodoc:
# description of the generator
DESCRIPTION = 'minimal HTML generator'
@@ -20,7 +24,7 @@ class Oldweb
# version of this generator
VERSION = '1'
- def initialize(store, options)
+ def initialize(store, options) # :nodoc:
# just because we're capable of generating UTF-8 to get human names
# right does not mean we should overuse it for quotation marks and such,
# our clients may not have the necessary fonts.
@@ -76,7 +80,7 @@ class Oldweb
end
end
- def generate
+ def generate # :nodoc:
setup
generate_class_files
generate_file_files
@@ -90,13 +94,13 @@ class Oldweb
end if src
end
- def rel_path(out_file)
+ def rel_path(out_file) # :nodoc:
rel_prefix = @outputdir.relative_path_from(out_file.dirname)
rel_prefix.to_s == '.' ? '' : "#{rel_prefix}/"
end
# called standalone by servelet
- def generate_class(klass, template_file = nil)
+ def generate_class(klass, template_file = nil) # :nodoc:
setup
current = klass
template_file ||= @template_dir + 'class.rhtml'
@@ -108,7 +112,7 @@ class Oldweb
end
# Generate a documentation file for each class and module
- def generate_class_files
+ def generate_class_files # :nodoc:
setup
template_file = @template_dir + 'class.rhtml'
current = nil
@@ -122,7 +126,7 @@ class Oldweb
end
# Generate a documentation file for each file
- def generate_file_files
+ def generate_file_files # :nodoc:
setup
@files.each do |file|
generate_page(file) if file.text?
@@ -130,7 +134,7 @@ class Oldweb
end
# Generate a page file for +file+
- def generate_page(file, out_file = @outputdir + file.path)
+ def generate_page(file, out_file = @outputdir + file.path) # :nodoc:
setup
template_file = @template_dir + 'page.rhtml'
rel_prefix = rel_path(out_file)
@@ -152,7 +156,7 @@ class Oldweb
end
# Generates the 404 page for the RDoc servlet
- def generate_servlet_not_found(message)
+ def generate_servlet_not_found(message) # :nodoc:
setup
template_file = @template_dir + 'servlet_not_found.rhtml'
rel_prefix = ''
@@ -164,7 +168,7 @@ class Oldweb
end
# Generates the servlet root page for the RDoc servlet
- def generate_servlet_root(installed)
+ def generate_servlet_root(installed) # :nodoc:
setup
template_file = @template_dir + 'servlet_root.rhtml'
@@ -178,7 +182,7 @@ class Oldweb
e!(e, "error generating servlet_root: #{e.message} (#{e.class})")
end
- def generate_table_of_contents
+ def generate_table_of_contents # :nodoc:
setup
template_file = @template_dir + 'table_of_contents.rhtml'
out_file = @outputdir + 'table_of_contents.html'
@@ -190,7 +194,7 @@ class Oldweb
e!(e, "error generating table_of_contents.html: #{e.message} (#{e.class})")
end
- def setup
+ def setup # :nodoc:
return if @outputdir
@outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
return unless @store
@@ -201,7 +205,7 @@ class Oldweb
end
# Creates a template from its components and the +body_file+.
- def assemble_template(body_file)
+ def assemble_template(body_file) # :nodoc:
body = body_file.read
head = @template_dir + '_head.rhtml'
tail = @template_dir + '_tail.rhtml'
@@ -211,7 +215,7 @@ class Oldweb
# Renders the ERb contained in +file_name+ relative to the template
# directory and returns the result based on the current context.
- def render(file_name)
+ def render(file_name) # :nodoc:
template_file = @template_dir + file_name
template = template_for(template_file, false, RDoc::ERBPartial)
template.filename = template_file.to_s
@@ -222,7 +226,7 @@ class Oldweb
# it out to +out_file+.
# Both +template_file+ and +out_file+ should be Pathname-like objects.
# An io will be yielded which must be captured by binding in the caller.
- def render_template(template_file, out_file = nil) # :yield: io
+ def render_template(template_file, out_file = nil) # :nodoc:
io_output = out_file && !@dry_run && @file_output
erb_klass = io_output ? RDoc::ERBIO : ERB
template = template_for(template_file, true, erb_klass)
@@ -242,14 +246,14 @@ class Oldweb
# Creates the result for +template+ with +context+. If an error is raised a
# Pathname +template_file+ will indicate the file where the error occurred.
- def template_result(template, context, template_file)
+ def template_result(template, context, template_file) # :nodoc:
template.filename = template_file.to_s
template.result(context)
rescue NoMethodError => e
e!(e, "Error while evaluating #{template_file.expand_path}: #{e.message}")
end
- def template_for(file, page = true, klass = ERB)
+ def template_for(file, page = true, klass = ERB) # :nodoc:
template = @template_cache[file]
return template if template
@@ -268,11 +272,11 @@ class Oldweb
@template_cache[file] = template
end
- def e!(e, msg)
+ def e!(e, msg) # :nodoc:
raise RDoc::Error, msg, e.backtrace
end
- def method_srclink(m)
+ def method_srclink(m) # :nodoc:
url = @old_vcs_url or return ""
line = m.line or return ""
path = URI.escape(m.file_name)
@@ -280,7 +284,7 @@ class Oldweb
end
# reach into RDoc internals to generate less HTML
- module LessHtml
+ module LessHtml # :nodoc:
def accept_verbatim(verbatim)
@res << "\n<pre>#{CGI.escapeHTML(verbatim.text.rstrip)}</pre>\n"
end
@@ -296,8 +300,10 @@ class Oldweb
end
end
+# :stopdoc:
class RDoc::Markup::ToHtml # :nodoc:
remove_method :accept_heading
remove_method :accept_verbatim
include Oldweb::LessHtml
end
+# :startdoc:
diff --git a/lib/rdoc/discover.rb b/lib/rdoc/discover.rb
index e497514..9450f42 100644
--- a/lib/rdoc/discover.rb
+++ b/lib/rdoc/discover.rb
@@ -1,5 +1,7 @@
+# :stopdoc:
begin
gem 'rdoc', '~> 4.1'
require_relative '../olddoc'
rescue Gem::LoadError
end unless defined?(Olddoc)
+# :startdoc:
--
EW
^ permalink raw reply related [relevance 5%]
Results 1-2 of 2 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2016-01-07 1:36 [PATCH 0/4] bunch of updates for 1.2 Eric Wong
2016-01-07 3:37 5% ` [PATCH 5/4] nodoc some internals Eric Wong
2016-01-09 22:34 7% [ANN] olddoc 1.2.0 - old-fashioned RDoc generator Eric Wong
Code repositories for project(s) associated with this public inbox
https://80x24.org/olddoc.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).